REST API 와 RESTful API? 무슨 단어 인가?

REST API란?

• REST(Representational State Transfer) API는 웹 서비스의 한 형태로 HTTP 프로토콜을 사용하여 클라이언트와 서버간에 데이터를 교환하는 방식을 말한다.

• Roy Fielding이 제안한 아키텍처 방식

REST의 구성요소로는

리소스: URI(Uniform Resource Identifier)를 통해 식별되는 자원

메소드: HTTP 메소드(GET, POST, PUT, DELETE 등)을 통해 자원에 대한 다양한 작업을 수행.

표현: JSON, XML 등과 같은 형식으로 자원을 표현

REST API 특징

Stateless 무상태성: 각 요청은 독립적이며, 클라이언트는 이전 요청 상태를 저장하지 않는다.

예시: HTTP요청마다 사용자 인증 토큰을 이용하여 서버가 사용자를 인증한다.

Cacheable 캐시가능: 응답은 캐시 가능해야 하며, 이를 통해 네트워크 효율성을 높일 수 있다.

Client-Server 클라이언트-서버 구조: 클라이언트와 서버는 독립적으로 동작하며, 각자 다른 기능에 집중할 수 있다.

Uniform Interface 일관된 인터페이스: 클라이언트와 서버간의 상호작용은 일관된 인터페이스를 통해 이루어져야한다.

예시: URI를 통해 리소스를 식별하고, HTTP 메소드를 통해 리소스에 대한 작업 수행

Layered System 계층 시스템: 클라이언트는 중간 계층을 통해 서버와 상호작용할 수 있다. ( 클라이언트가 직접 서버와 상호작용하는지 여부를 알 필요가 없음)

예시: 로드 밸런서를 통해 요청을 분산시켜 서버의 부하를 관리

REST API 설계원칙

1. 자원의 명확한 식별 (Resource Identification)

• 정의: 모든 리소스는 고유한 URI로 식별되어야 합니다.
• 설명: URI는 자원을 나타내야 하며, 명사로 표현됩니다.
• 예시:
• 사용자 목록: /users
• 특정 사용자: /users/{id}
• 사용자의 주문: /users/{id}/orders

2. HTTP 메서드의 적절한 사용 (Use of HTTP Methods)

• 정의: HTTP 메서드를 사용하여 자원에 대한 작업을 수행합니다.
• 설명: 각 메서드는 특정 CRUD(생성, 읽기, 업데이트, 삭제) 작업을 수행하는 데 사용됩니다.
• 예시:
• GET /users: 사용자 목록 조회 (Read)
• POST /users: 새 사용자 생성 (Create)
• PUT /users/{id}: 사용자 정보 업데이트 (Update)
• DELETE /users/{id}: 사용자 삭제 (Delete)

3. HTTP 상태 코드 사용 (Use of HTTP Status Codes)

• 정의: 클라이언트의 요청 결과를 HTTP 상태 코드를 통해 나타냅니다.
• 설명: 각 응답은 요청의 성공 또는 실패를 나타내는 상태 코드를 포함해야 합니다.
• 예시:
• 200 OK: 성공적인 요청
• 201 Created: 리소스 생성 성공
• 400 Bad Request: 잘못된 요청
• 404 Not Found: 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버 오류

4. 데이터 포맷 일관성 (Consistent Data Formats)

• 정의: 응답 데이터 형식은 일관성이 있어야 합니다.
• 설명: 일반적으로 JSON 또는 XML 형식을 사용하며, 클라이언트가 데이터 형식을 선택할 수 있도록 콘텐츠 협상(Content Negotiation)을 지원합니다.
• 예시:
• JSON 응답: Content-Type: application/json
• XML 응답: Content-Type: application/xml

5. HATEOAS (Hypermedia as the Engine of Application State)

• 정의: 응답은 관련된 리소스에 대한 링크를 포함해야 합니다.
• 설명: 클라이언트는 응답에 포함된 링크를 통해 다음 가능한 작업을 탐색할 수 있습니다.
• 자세한 설명은 본문 아래 단에 추가

6. 버전 관리 (Versioning)

• 정의: API의 변경 사항을 관리하기 위해 버전 관리를 수행합니다.
• 설명: URL 경로, 요청 헤더 등을 통해 버전을 명시합니다.
• 예시:
• URL 경로에 버전 포함: /v1/users
• 요청 헤더에 버전 포함: Accept: application/vnd.example.v1+json

7. 보안 (Security)

• 정의: API는 적절한 인증 및 권한 부여 메커니즘을 사용하여 보호되어야 합니다.
• 설명: 토큰 기반 인증, OAuth, API 키 등을 사용하여 보안을 강화합니다.
• 예시:
• JWT(Json Web Token) 사용
• OAuth 2.0 인증

8. 유효성 검사 (Validation)

• 정의: 클라이언트에서 전송된 데이터를 철저히 검증합니다.
• 설명: 유효성 검사 오류는 적절한 HTTP 상태 코드와 함께 명확한 메시지를 반환해야 합니다.
• 예시:
• 필수 필드 누락: 400 Bad Request
• 데이터 형식 오류: 422 Unprocessable Entity

9. 효율적인 페이징과 정렬 (Efficient Paging and Sorting)

• 정의: 많은 양의 데이터를 다룰 때 효율적인 페이징과 정렬 기능을 제공해야 합니다.
• 설명: 클라이언트가 필요한 데이터만 요청할 수 있도록 페이징, 정렬, 필터링 기능을 지원합니다.
• 예시:
• 페이징: GET /users?page=2&size=10
• 정렬: GET /users?sort=name,asc

RESTful API란?

REST API 설계 원칙을 잘 구현한 API를 의미한다.

REST API가 인터페이스로 비유하면 RESTful API는 인터페이스 구현체이다.

RESTful API를 만들기 위해서는

명확하고 일관성 있는 URI를 사용해야 한다.

URI의 리소스는 명사를 사용해야하고 API버전은 URL이나 헤더에 포함한다.

GET /api/getuser X

GET /api/user O

동작을 설명하는 동사 대신 HTTP 메소드를 사용하여야 함

HTTP 메소드를 잘 구분해서 쓰면 같은 URI로 명확한 요청이 가능하다.

상태코드의 적절한 사용, 각 응답에 상태코드를 사용하여 요청의 결과를 클라이언트에 전달한다.

HATEOAS란?

클라이언트에서 API 요청을 하였을 때, 다음 동작을 위해 API 문서를 찾아보지 않더라도 다음 필요한 작업을 수행할 수 있도록 현재 리소스에 대한 링크를 포함하는 것을 말한다.

{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "links": [
    {
      "rel": "self",
      "href": "/users/1"
    },
    {
      "rel": "update",
      "href": "/users/1",
      "method": "PUT"
    },
    {
      "rel": "delete",
      "href": "/users/1",
      "method": "DELETE"
    },
    {
      "rel": "friends",
      "href": "/users/1/friends"
    }
  ]
}

유저 정보를 제공하는 API이다. 해당 정보에 관련된 URL을 제공한다.

이 정보를 제공받음으로서 클라이언트 측에서는 서버의 상태와 행동, 변동을 인지하지 않고있어도 된다.

HATEOAS를 통해 RESTful한 API를 구현할 수 있다.