REST API 설계 규칙

date

May 27, 2023

slug

rest-api-design-rule

author

status

Public

Resource Archetypes

Document

하나의 문서를 지칭한다. 보통 단수 형식으로 정의한다.


api.cricket.restapi.org/leagues/{id}
api.cricket.restapi.org/leagues/ipl

Collection

리소스를 담는 집합체를 지칭한다. 복수 형식으로 정의한다.


api.cricket.restapi.org/leagues
api.cricket.restapi.org/leagues/{id}/teams

Controller

CRUD(create retrieve update delete) 이외의 method를 실행해야할 때 사용된다.


POST api.example.com/alerts/245743/resend

URI Path Design

Document & Collection 예시

HTTP Method	URL design	Description
GET	api.bank.lk/v1/banks	collection의 목록 조회
POST	api.bank.lk/v1/banks	새로운 document 리소스 생성
GET	api.bank.lk/v1/banks/{id}	하나의 document 조회
PUT	api.bank.lk/v1/banks/{id}	하나의 document 대체
PATCH	api.bank.lk/v1/banks/{id}	하나의 document 부분 수정
DELETE	api.bank.lk/v1/banks/{id}	하나의 document 삭제

Rule: document 이름은 단수형으로 한다


api.cricket.restapi.org/leagues/ipl

Rule: collection 이름은 복수형으로 한다


api.cricket.restapi.org/leagues/ipl/teams

Rule: controller 이름은 동사로 한다


api.college.restapi.org/students/morgan/register
api.ognom.restapi.org/dbs/reindex

Rule: CRUD 동사는 controller 이름으로 사용하지 않는다 (HTTP method - POST, GET, PUT, DELETE를 통해서 리소스 CRUD 실행한다)

URI Query Design

Rule: 리소스의 세부 사항을 정의한다


api.college.restapi.org/students/morgan/send-sms
api.college.restapi.org/students/morgan/send-sms?text=hello

Rule: 집합체 조회시 필터링 용도로 사용될 수 있다


GET /users
GET /users?role=admin

Rule: 집합체 페이지 단위 조회 용도로 사용될 수 있다


GET /users?limit=25&offset=50

Identifier Design with URIs

Rule: Forward slash(/)를 사용하여 계층적인 관계를 표현한다


api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares

Rule: 가독성을 높이기 위한 구분자로 Hyphen(-)을 사용한다


api.example.restapi.org/blogs/mark-masse/entries/my-first-post

Rule: Underscore(_)는 사용하지 않는다 (단, Query parameter는 Body paramter와 일관성을 유지하기 위해 snake_case를 사용한다)

Rule: 소문자를 사용한다

Other Special Rule

Rule: PATCH method는 사용하지 않고 대신 PUT method를 사용한다. (PATCH의 경우 나중에 추가되어 고객사의 방화벽에 막혀있는 경우가 종종 있다)

Rule: 목록 조회시 매개변수(Query parameter)가 많거나 개인 정보 보호가 필요한 변수가 존재하는 경우 Controller Archetype을 추가할 수 있다.

매개변수가 많은 경우 GET 목록 조회(매개변수가 거의 없는) 기본적으로 제공하고 예시와 같이 search Controller Archetype을 추가적으로 제공하는 것을 권장한다.


GET /v1/wallets/{id}/transactions?start_date=2023-01-01&end_date=2023-07-01&type=deposit&amount_min=100&amount_max=500..

(목록에서 다양한 조건으로 검색해야 하는 경우 조건 변수가 많을 수 있으므로 아래와 같이 Controller Archetype을 제공할 수 있다)

POST /v1/wallets/{id}/transactions/search
{
  "start_date": "2023-01-01",
  "end_date": "2023-07-01",
  "type": "deposit",
  "amount_min": 100,
  "amount_max": 500,
  ...
}

Rule: Body paramter는 특별한 사유가 없으면 JSON 포맷을 따른다. (단, 변수 이름은 snake_case 표기법을 따른다)

Rule: 집합체에 대한 목록 조회시 필요한 경우 Pagination을 적용한다.


REQUEST GET http://api.sentbe.com/teams/1/employees&offset=0&limit=20
RESPONSE {
  data: [
    { name: kim, job: developer },
    { name: park, job: developer },
    …
  ],
  total: 1000, // 전체 갯수
  count: 20, // 현재 페이지의 결과 갯수
  offset: 0, // 현재 쿼리의 offset
  limit: 20 // 현재 쿼리의 limit
}