1. 기본 규칙
Resource 이름에는 동사 대신 되도록 명사를 사용합니다.
명사는 단수보다는 복수를, 구체적인 이름을 사용하도록 합니다. 하나 밖에 존재하지 않는 Resource 에 대해서는 단수를 사용하여도 무방합니다.
/members : 회원정보
/products : 상품정보
각 Resource 이름별로 되도록 2개의 기본 URL을 제공합니다.
/products : 상품정보의 Collection
/products/{productId} : 상품정보 Element
HTTP Verb 를 사용하여 Operation 을 표현합니다.
GET/POST/PUT/DELETE 를 사용하여 기본 Operation 을 표현합니다.
- GET - Read
- POST - Create
- PUT - Update
- DELETE - Delete
/products
GET - 상품의 목록을 조회한다
POST - 새로운 상품을 생성한다
PUT - 상품들 전체 혹은 복수개를 갱신한다.
DELETE - 전체 상품을 삭제한다.
/products/2345
GET - 2345번 상품을 조회한다.
POST - Error. 새로운 상품의 생성은 POST /products로 수행했어야 함.
PUT - 2345번 상품이 존재시 갱신한다. 존재하지 않는다면 Error.
DELETE - 2345번 상품을 삭제한다.
Resource간의 관계는 간단하게 유지하며 URL 계층을 이용하여 표현합니다
/resource/{id}/resource
예시
GET /products/2345/seller - 2345 번 상품에 대한 셀러를 조회한다.
POST /products/2345/seller - 2345 번 상품에 대한 셀러를 등록한다.
GET /orders/293845/ship-address - 293845 번 주문에 대한 배송지를 조회한다.
Query Parameter 를 통해 속성 및 상태에 대한 검색을 지원할 수 있습니다.
Collection 에 대한 조회 API 들은 Query Parameter 를 통해 속성 및 상태에 대한 검색을 지원하는 것이 가능합니다.
GET /v1/products?seller=345566&category=2123
Query Parameter 를 통해 MultiID 조회를 지원할 수 있습니다
MultiID 조회 예
GET /product/v1/products?productNos=1244821950,1244821951,1244821952,1244821953,1244821954
단건 조회
GET /product/v1/products/{productNo}
Query Parameter 를 통해 Paging 을 지원 할 수 있습니다.
Collection 에 대한 조회 API 들은 다음과 같은 limit 와 offset Query Parameter를 통해 Paging을 지원 할 수 있습니다.
Paging 지원 예시
GET /v1/products?offset=50&limit=15
2. 세부 규칙
모든 API는 /v{n} 과 같은 접두어로 Version을 가집니다.
최초로 정의되는 모든 API들은 모두 /v1 의 접두어를 가져야 합니다.
/v1/products
/v1/products/2345/seller
이미 공개된 API의 요청 및 응답 규격이 호환성을 깨트리는 경우 Version을 증가시켜 새롭게 정의 되어야 합니다. API의 호환성에 대한 규칙은 별도의 문서에서 정의합니다.
/v2/products
/v2/products/2345/seller
Default로 고정된 갯수의 응답을 반환하는 API는 다른 갯수의 응답 반환을 지원합니다.
특정한 갯수의 응답을 반환하도록 정의된 API들은 Optional Query Parameter로 다른 갯수를 응답 할 수 있어야 합니다.
/v1/users/0923837/recommendation : 회원번호 0923837 의 사용자를 위한 추천 상품 조회 (기본 15개 반환)
/v1/users/0923837/recommendation?limit=30 : 회원번호 0923837 의 사용자를 위한 추천 상품 조회 30개 조회
HTTP Status Code를 이용하여 요청의 처리 결과를 나타냅니다.
요청된 API의 응답의 상태는 아래 정의된 HTTP Status Code를 이용합니다.
- 200 : OK. 요청 처리가 성공함
- 201 : Created. 생성 요청이 성공함
- 304 : Not Modified. (브라우저와 웹서버등에서 이용)
- 400 : Bad Request. Request의 정보가 누락되거나 잘못됨
- 401 : Unauthorized. Request의 인증정보가 틀림
- 403 : Forbidden. 해당 Resource에 대한 접근 권한이 없음
- 404 : Not Found. 요청한 Resource가 존재 하지 않음
- 412 : Precondition Failed. (브라우저와 웹서버간에 이용)
- 500 : Internal Server Error. 서버에서 알 수 없는 오류 발생
에러 발생의 경우 아래의 형식의 에러 메세지를 반환합니다.
4XX, 5XX과 같은 에러 응답의 경우 다음과 같은 형식의 에러 메세지를 반환합니다.
에러메시지 반환 예시
{
"status" : 400, // Number, Http Status Code
"message" : "Seller 정보가 필요합니다.", // String, Error Message
"code" : 20003 // Number, Application Specific Error Code
}
위에 정의된 세가지 이외에 추가적인 필드의 정의는 가능하나 추가 정의시 문서에 명시되어야 합니다.
응답 메세지 형식
- 모든 API는 JSON 형식의 응답을 기본으로 하며, 이럴 경우
application/json의 MIME Type을 가져야합니다. - JSON 이외의 응답 지원이 필요한 경우는 문서에 명시되어야 하며, 요청하는 Client에서는
Accept헤더를 이용하여 Request에 명시합니다.
대소문자의 사용
- URI Path는 소문자만으로 구성되어야 합니다.
- JSON 응답의 속성은 camel case를 사용합니다.
- Query 파라매터의 경우 camel case를 사용합니다.
/v1/products?categoryName=cosmetic
{
productId : "10001",
name : "키엘 수분크림 120ml"
categoryName : "cosmetic",
price : 46700
}
