RESTful API

오늘 팀프로젝트를 위해 API명세서를 작성했는데 올바르지 않은 명세서라고 반려당했다. 그래서 확실하게 아는것같지

않아서 더 자세히 알아보려 한다.

 

RESTful API란 무엇이며, 왜 탄생했는가?

RESTful API는 Representational State Transfer(REST) 원칙을 기반으로 설계된 API입니다. REST는 2000년 Roy Fielding의 박사 논문에서 처음 정의된 개념으로, 웹 아키텍처의 일관성과 효율성을 극대화하기 위해 제안되었습니다. RESTful API는 이 원칙을 구현한 API를 말하며, 단순히 HTTP를 사용하는 것만으로는 RESTful하다고 할 수 없습니다.

RESTful API는 리소스를 중심으로 설계된 구조와 HTTP의 표준 사용을 통해 클라이언트와 서버 간의 통신을 간소화하고 효율적으로 만듭니다. 이는 단순히 데이터를 주고받는 기술 이상의 철학으로, 현대 웹의 설계와 개발에 지대한 영향을 미쳤습니다.

 

RESTful API의 핵심 원칙과 철학

RESTful API가 REST의 원칙을 따르기 위해 충족해야 하는 주요 조건은 다음과 같습니다:

1. 리소스 중심 설계

REST에서는 모든 것을 리소스(Resource)로 간주합니다.

• 리소스는 데이터를 나타내며, 예를 들어 사용자, 주문, 상품 등이 리소스가 될 수 있습니다.
• 각 리소스는 고유한 URI(Uniform Resource Identifier)로 식별됩니다.
  • 예: /users(사용자 목록), /users/123(ID가 123인 사용자)

리소스 중심 설계의 목표는 데이터를 명확히 정의하고 이를 직관적으로 접근 가능하게 하는 것입니다.

 

잘못된 설계 예시:

• /getUser?id=123 (행위 중심 URI)

올바른 설계:

• /users/123 (리소스 중심 URI)

2. HTTP 메서드의 의미에 맞는 사용

RESTful API는 HTTP 메서드를 사용하여 리소스에 대한 작업을 표현합니다.
각 메서드는 특정 작업의 의미를 나타내며, 다음과 같이 매핑됩니다:

• GET: 리소스를 조회 (읽기 작업)
  • 예: /users는 모든 사용자 목록을 반환.
  • 예: /users/123는 ID가 123인 사용자를 반환.
• POST: 새로운 리소스를 생성
  • 예: /users에 새 사용자 데이터 추가.
• PUT: 리소스의 전체 업데이트
  • 예: /users/123의 모든 데이터를 변경.
• PATCH: 리소스의 부분 업데이트
  • 예: /users/123의 특정 필드(이름 등)만 변경.
• DELETE: 리소스를 삭제
  • 예: /users/123 사용자를 삭제.

3. 무상태성(Statelessness)

REST는 무상태성을 강력히 요구합니다:

• 서버는 클라이언트의 상태를 기억하지 않아야 합니다.
• 모든 요청은 독립적이며, 필요한 모든 정보(인증 토큰, 데이터 등)를 포함해야 합니다.

예를 들어, 클라이언트가 /users/123에 요청을 보낼 때, 이전 요청에 의존하지 않고도 이를 처리할 수 있어야 합니다.
무상태성의 장점:

• 서버 확장이 쉬워짐: 클라이언트 상태를 기억하지 않아 부하 분산 가능.
• 요청 처리의 독립성 보장.

4. 표현의 다양성(Representation)

RESTful API는 리소스를 표현하는 형식을 제한하지 않습니다.

• JSON, XML, HTML 등 다양한 데이터 형식 사용 가능.
  예:

{
  "id": 123,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

5. 일관된 인터페이스(Uniform Interface)

RESTful API의 강점은 일관된 인터페이스를 제공하는 것입니다.

• URI, 메서드, 상태 코드 등은 모든 리소스에 대해 일관된 설계 원칙을 따릅니다.
• 클라이언트는 설계의 일관성 덕분에 쉽게 API를 이해하고 사용할 수 있습니다.

6. 하이퍼미디어(HATEOAS)

RESTful API는 하이퍼미디어를 통해 클라이언트가 API를 탐색할 수 있도록 지원해야 합니다.

• 응답 데이터에 관련 작업 링크를 포함해 사용자가 가능한 동작을 직관적으로 이해할 수 있게 합니다. 예:

{
  "id": 123,
  "name": "John Doe",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "orders", "href": "/users/123/orders" }
  ]
}

---

REST의 탄생 배경과 목적

REST는 웹 아키텍처가 복잡해지던 시기에 더 단순하고, 확장 가능하며, 효율적인 설계 원칙을 제시하기 위해 탄생했습니다.

1. 웹 표준화의 필요성

1990년대 웹이 빠르게 성장하며 클라이언트-서버 간 통신 방식이 다양해졌습니다.
하지만 당시에는:

• 각 서비스마다 API 설계 방식이 달랐습니다.
• 통신 방식이 비표준적이고 비효율적이었습니다.

REST는 HTTP의 설계 철학을 기반으로, 일관된 표준화된 아키텍처를 제공했습니다. 이를 통해 클라이언트와 서버 간의 상호작용을 통합하고 간소화할 수 있었습니다.

2. 확장성과 유지보수성

웹 시스템이 대규모로 확장됨에 따라 무상태성, 계층 구조 등의 원칙이 필요해졌습니다.

• 무상태성: 상태 저장을 피함으로써 서버 확장이 용이.
• 계층화: 프록시, 로드 밸런서를 통해 확장성과 보안을 향상.

3. 단순성과 직관성

SOAP 같은 초기 웹 서비스 프로토콜은 복잡하고 무겁다는 단점이 있었습니다. REST는 이를 단순화하여:

• 직관적인 URI 설계.
• 명확한 HTTP 메서드 활용.
• 상태 코드로 요청 결과를 간단히 표시.

4. 플랫폼 독립성

REST는 데이터 표현 방식에 제한을 두지 않으며 JSON, XML, HTML 등 다양한 포맷을 지원합니다. 이는 모바일, 웹, IoT 등 다양한 클라이언트와 서버 간의 플랫폼 독립적 통합을 가능하게 했습니다.

---

RESTful API의 의의와 한계

의의

• 표준화: REST는 웹 개발에서 표준화된 설계를 제공합니다.
• 확장성: 무상태성과 계층 구조를 통해 대규모 시스템에서도 안정적으로 작동.
• 개발자 경험 개선: 일관적이고 직관적인 설계로 사용과 학습이 쉬움.
• 호환성과 유연성: 다양한 플랫폼과 기기에서 쉽게 통합 가능.

한계

• 복잡한 트랜잭션 처리: 여러 리소스에 걸친 트랜잭션 구현이 어렵습니다.
• 실시간 데이터 통신: REST는 요청-응답 모델이므로 WebSocket 같은 실시간 통신에는 적합하지 않습니다.
• HATEOAS 구현 어려움: 실제로 하이퍼미디어를 철저히 구현한 API는 드뭅니다.

REST는 현대 웹 시스템의 설계 철학에 깊은 영향을 미쳤으며, 현재도 GraphQL, gRPC 같은 기술과 함께 현대 웹의 중요한 설계 방식으로 자리 잡고 있습니다.

 

---

 

올바른 API 명세서

 

올바른 API 명세서는 API의 구조, 사용 방법, 요청 및 응답에 대한 세부 사항을 일관되게 정의하여 개발자들이 쉽게 이해하고 사용할 수 있도록 작성해야 합니다. 아래는 올바른 API 명세서를 작성하기 위한 핵심 요소와 예시입니다.

 

API 명세서 작성 핵심 요소

1. API의 목적과 개요

• API가 제공하는 주요 기능과 목적을 간단히 설명.
• 사용 대상(예: 프론트엔드, 제3자 개발자 등) 명시.

2. 기본 정보

• Base URL: API의 기본 엔드포인트.
  • 예: https://api.example.com/v1
• 인증 방식: 사용 가능한 인증 메서드 설명.
  • 예: OAuth2, API 키, JWT 등.

3. 엔드포인트 정의

각 엔드포인트마다 다음 정보를 포함:

• URI: 요청 경로.
• HTTP 메서드: 요청 유형 (GET, POST, PUT, DELETE 등).
• 설명: 엔드포인트의 기능 설명.
• 요청 헤더: 필수 헤더와 선택 헤더 정의.
• 요청 파라미터: Query, Path, Body 등의 파라미터.
• 응답 데이터: 성공 및 실패 시 반환되는 데이터 구조.
• HTTP 상태 코드: 각 상황에 따른 상태 코드 설명.

4. 예제 요청과 응답

• 실제 사용 사례를 기반으로 JSON 또는 cURL 등으로 예제를 작성.
• 요청 및 응답 데이터를 명확히 제공.

5. 에러 처리

• 에러 코드와 메시지를 문서화.
• 각 에러의 발생 조건과 해결 방법을 기술.

---

API 명세서 예시

1. API 개요

API Name: Example User Management API  
Version: v1  
Base URL: https://api.example.com/v1  
Description: 사용자 계정을 관리하는 API로, 회원 가입, 로그인, 사용자 정보 조회 및 업데이트를 지원합니다.

---

2. 인증

Authorization: Bearer <token>
- 모든 요청은 헤더에 JWT 토큰을 포함해야 합니다.
- 토큰은 `/auth/login` 엔드포인트를 통해 발급받을 수 있습니다.

---

3. 엔드포인트

3.1. 사용자 조회

• URI: /users/{userId}
• HTTP Method: GET
• Description: 특정 사용자의 정보를 조회합니다.

요청

Headers:
  Authorization: Bearer <token>

Path Parameters:
  userId (string, required): 조회하려는 사용자의 고유 ID.

Example Request:
GET /users/12345
Host: api.example.com
Authorization: Bearer abc.def.ghi

응답

• 200 OK

{
  "id": "12345",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2023-01-01T12:00:00Z"
}

• 404 Not Found

{
  "error": {
    "code": 404,
    "message": "User not found"
  }
}

---

3.2. 사용자 생성

• URI: /users
• HTTP Method: POST
• Description: 새 사용자를 생성합니다.

요청

Headers:
  Content-Type: application/json
  Authorization: Bearer <token>

Body Parameters:
  name (string, required): 사용자 이름.
  email (string, required): 사용자 이메일.
  password (string, required): 계정 비밀번호.

Example Request:
POST /users
Host: api.example.com
Authorization: Bearer abc.def.ghi
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "password": "securepassword123"
}

응답

• 201 Created

{
  "id": "67890",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "createdAt": "2023-01-01T12:00:00Z"
}

• 400 Bad Request

{
  "error": {
    "code": 400,
    "message": "Invalid email format"
  }
}

---

3.3. 사용자 삭제

• URI: /users/{userId}
• HTTP Method: DELETE
• Description: 특정 사용자를 삭제합니다.

요청

Headers:
  Authorization: Bearer <token>

Path Parameters:
  userId (string, required): 삭제할 사용자의 고유 ID.

Example Request:
DELETE /users/12345
Host: api.example.com
Authorization: Bearer abc.def.ghi

응답

• 204 No Content

No Response Body

• 403 Forbidden

{
  "error": {
    "code": 403,
    "message": "Unauthorized to delete this user"
  }
}

---

4. 에러 코드

상태 코드 메시지 설명

200	OK	요청 성공.
201	Created	리소스 생성 성공.
204	No Content	리소스 삭제 성공.
400	Bad Request	잘못된 요청 파라미터.
401	Unauthorized	인증 실패.
403	Forbidden	접근 권한 부족.
404	Not Found	리소스가 존재하지 않음.
500	Internal Server Error	서버 내부 오류.

---

좋은 API 명세서의 특징

1. 명확하고 간결함: 불필요한 정보를 배제하고, 사용자가 이해하기 쉽게 작성.
2. 일관성: URI 설계, 상태 코드, 응답 포맷 등이 모든 엔드포인트에서 동일한 기준을 따름.
3. 예제 제공: 요청 및 응답의 실제 예제를 포함하여 개발자가 테스트하기 쉽게 작성.
4. 에러 처리 명확화: 에러 상황과 대응 방법을 상세히 기술.
5. 갱신 주기: API 변경 시 명세서를 최신 상태로 유지.

올바른 API 명세서는 개발자 간의 협업을 원활하게 하고, 서비스 사용자의 만족도를 높이는 데 중요한 역할을 합니다.