Rest API 디자인 가이드

이 글은 5 Basic Rest API Design Guidelines 을 정리한 글 입니다.

API를 디자인할 때 다음 사항을 고려해보면 좋다.

  • 문헌에 설명된 RESTful API 원칙
  • 구글, 마이크로 소프트 및 IT 대기업에서 사용하고 있는 관행

RESTful API를 만드는 5가지 기본 설계 지침이 있다.

  • Resources
  • HTTP Method
  • HTTP Headers
  • Query Parameter
  • Status Code

1. Resources

  • 리소스를 설명할 때 가능하면 동사가 아닌 구체적인 명사를 사용해라
    • GET /users/1234
    • POST /users
    • DELETE /users/1234
  • URI case : CamelCase, snake_case, spinal-case 중에서 가능하면 spinal-case를 사용해라. (구글, 페이팔과 같은 회사에서도 spinal-case를 사용하고 있다.)

2. HTTP Methods

REST는 HTTP 프로토콜을 사용한다. RESTful API는 HTTP 메소드를 사용하여 리소스에 어떤 액션이 수행되는지를 나타낸다.

  • GET : GET 메소드는 리소스를 가져오는데 사용된다. GET 요청은 데이터를 가져오기만 해야하며 데이터에 영향을 주면 안된다.
  • HEAD : GET과 동일하지만 status line과 header section만 전송한다.
  • POST : 서버에 데이터를 전달하는데 사용된다.
  • PUT : 리소스를 업로드된 컨텐츠로 업데이트하는데 사용된다.
  • DELETE : 리소스를 삭제하는데 사용된다.

3. HTTP headers

HTTP 헤더는 요청 또는 응답 또는 엔티티 바디에 대한 정보를 제공한다. HTTP header에는 4가지 타입이 있다.

  • General Header : 요청 및 응답 메시지 모두에 포함될 수 있다.
  • Client Request Header : 요청 메시지에만 포함 될 수 있다.
  • Sever Response Header : 응답 메시지에만 포함 될 수 있다.
  • Entity Header : 엔티티 바디에 대한 메타 정보와 관련된 헤더이다.

4. Query parameters

  • Paging : 리턴해야하는 데이터의 양이 많거나 예측하기 어려운경우는 페이징 처리를 하는것이 좋다.
  • Filtering : 속성의 기대값을 지정하여 리소스를 필터링한다. 하나의 속성에 여러개의 기대값으로 필터링하는것이 가능하며 한번에 여러개의 속성으로 필터링 하는것도 가능하다.
  • Sorting : 리소스를 정렬한다. sort 파라미터는 정렬을 수행할 속성의 이름을 포함해야 한다.
  • Searching : 검색 파라미터는 Filter와 유사하게 전달되지만 정확한 값이 아니여도 되며 대략적으로 일치하기만 하면 된다.

5. Status Code

RESTFul API에서 적절한 HTTP 상태 코드를 사용하는 것은 매우 중요하다. 주로 사용되는 상태 코드는 아래와 같다.

  • 200 - OK
  • 201- CREATED : 리소스가 생성된 경우
  • 204 - NO CONTENT : 리소스가 성공적으로 삭제된 경우 혹은 응답 바디가 없는 경우
  • 304 - NOT MODIFIED : 데이터가 변경되지 않음 (캐시된 데이터를 사용해라)
  • 400 - BAD REQUEST : 요청이 유효하지 않음
  • 401 - UNAUTHORIZED : 사용자 인증이 필요함
  • 403 - FORBIDDEN : 리소스에 대한 접근이 허용되지 않음
  • 404 - NOT FOUND : 리소스가 없음
  • 500 - INTERNAL SERVER ERROR : 요청을 처리하는 중 알 수없는 에러가 발생함. API 개발자는 가능하면 이 에러는 피해야한다.