Skip to content

CodingGuidelines:REST

HTTP Methods

Web developers are likely familiar with GET and POST, along with the other HTTP methods, also sometimes called HTTP verbs. These methods define the type of request being made to a REST API.

Common HTTP methods include:

  • GET: retrieve data, the equivalent to a read in CRUD APIs
  • POST: add new data
  • PUT: update existing data
  • PATCH: update a subset of existing data
  • DELETE: remove data

While there are other methods, they are rarely seen in REST APIs. The method itself does not mean much without the target, the resource.

나의 경우

  • GET: 데이터 획득. (SQL Select)
  • PATCH: 이미 존재하는 데이터를 업데이트. (SQL Update)
    • Wikipedia 주석: 패치(patch)는 수정 또는 개선을 위해 컴퓨터 프로그램이나 지원 데이터를 업데이트하도록 설계된 일종의 소프트웨어이다.
  • DELETE: 데이터 제거. (SQL Delete)
  • POST: 데이터 추가. (SQL Insert, Upsert 포함) 및 무엇인가 연산(?)할 경우. 그냥, 위의 Get, Patch, Delete 가 아닌 경우 사용.

그 밖의 요청 적용.

  • HEAD: GET과 동일. 단, "Response Content"가 존재할 경우 제거한다. - 정확한 사용법은 나중에 확인.
  • CONNECT: 터널링 전용. Answer 에서 Task 와 직접 통신할 경우 사용한다. - 정확한 사용법은 나중에 확인.
  • OPTIONS: 브라우저에서 통신 설정을 위해 사용되고 있다. 즉, 사용 금지. - 정확한 사용법은 나중에 확인.
  • TRACE: 디버깅용. - 정확한 사용법은 나중에 확인.

사용해야 하나?

  • PUT: 메서드는 목적 리소스 모든 현재 표시를 요청 payload로 바꿉니다. -> request payload 로 바꾼다는 의미인가?

Resource Names

Resources are sometimes referred to as the nouns that the HTTP verbs act upon. Earlier web services were built around remote procedure calls, which saw APIs as extensions of the code that called them. By contrast, REST resources can be accessed with multiple HTTP methods, which makes them less analogous to a procedure call.

Example

For example, if your API stored animals, a resource name might be "animals." And the path to access that resource might be /api/animals. The resource would then be combined with HTTP methods like so:

  • GET /api/animals: retrieve a list of animals
  • POST /api/animals: add a new animal
  • GET /api/animals/cat: retrieve a single animal by ID
  • PUT /api/animals/cat: update a single animal by ID
  • DELETE /api/animals/cat: delete an animal by ID

나의 경우

그 자체를 나타낼 경우 단수, 하위 목록을 나타낼 경우 복수로 표현.

예를 들어, "할당된 포트 번호 목록"과 "할당 할 수 있는 포트 번호 범위(최대, 최소 값 쿼리)" 두 가지 항목을 표현할 때,

  • GET /api/posts - 할당된 포트 번호 목록
  • GET /api/posts/99 - 99번 포트 번호의 정보
  • GET /api/post/range - 할당 할 수 있는 포트 번호 범위

라우팅시 예외 조건 제거

예를 들면 /users/{id} 와 /users/statistics 를 공존하게 하려면 다음과 같은 예외 처리가 필요하다.

  1. /users/statistics URL이 발견되면 먼저 라우팅 한다.
  2. /users/{id} 에서 {id}는 statistics이 되면 안된다.

서버의 경로기반 라우팅시 불필요한 조건을 추가하게 되고 처음 코드를 접할수록 이러한 예외 처리는 복잡도를 증가시킨다.

더 나은 REST API를 설계하는 법

  • How to design better APIs
  • 일관성 유지 : URL/헤더/인증/상태코드..
  • ISO8601 UTC 날짜 포맷 사용
  • Public Endpoint만 인증 예외. 나머지는 모두 인증 필수
  • 헬스 체크 Endpoint 제공
  • API 버저닝
  • API 키 인증 적용
  • 합리적인 HTTP 상태코드 와 메소드 사용
  • 각 Endpoint에 자체만으로 설명 가능한 간단한 이름을 사용
  • 표준 에러 응답 사용
  • POST에서 생성된 자원을 리턴
  • PUT 대신 PATCH
  • 최대한 구체적으로
  • Pagination 사용
  • 각 자원을 확장 가능하게 (expand 등의 쿼리 파람을 줘서 추가 정보도 리턴 가능하게 설계)

See also

Favorite site

Reference site