본문
REST API 설계 (네이밍)
필자는 현재 Open API 서비스를 개발/운영을 담당하고 있다. 신규 API URL을 네이밍 할 때마다 정체성의 혼란이 오는것을 느낀다. 이번 기회에 RESTful한 API 네이밍 방법을 정리하여 필자의 전두엽에 평안을 주기위해 이 글을 작성한다.
📌 목차
1. REST란?
2. Resource 표현방식
3. REST API 설계
4. REST API Sample
1. REST란?
Representational State Transfer의 약자이며, 다음과 같이 구성되어 있다.
- 자원(Resource): URI
- 행위(Verb): HTTP Method
- 표현(Representations)
즉 REST는 URI를 통해 자원(Resource)을 표시하고, HTTP Method를 기반으로 해당 자원의 행위를 규정하여 그 결과를 받는 것을 말한다.
HTTP Method는 크게 GET, POST, PUT, DELETE가 대표적이며, 일반적으로 CRUD(Create, Read, Update, Delete)에서 조회는 GET, 등록은 POST, 수정은 PUT, 삭제는 DELETE를 이용한다.
* Resource의 여러가지 형태
1. Resource는 단건일 수 있고, 단건의 집합일 수 있다.
- 손님: /customer
- 손님들 : /customers
- 2번 ID를 가진 손님 : /customers/2
2. Resource는 서브Resource를 포함할 수 있다.
손님들의 계좌를 관리한다면, 손님의 하위에 계좌를 포함할 수 있다.
- 2번 손님의 모든 계좌 : /customers/2/accounts
- 2번 손님의 2번 계좌 : /cusotmers/2/accounts/2
2. Resource 표현방식
Resource는 표현방식에 따라 document, collection, store, controller 4가지로 나눌수 있다.
2.1 Document
Document는 1개의 개체를 나타내는 것으로 객체 인스턴스, DB의 record와 유사한 개념을 갖는다.
REST에서는 리소스 집합(collection)중 하나로 표현되어지며 일반적으로 collection의 뒤에 '/'를 통해 구분한다.
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin
2.2 Collection
Collection은 단일 Resource(document)들의 묶음을 의미한다. 복수형 단어를 사용한다.
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
2.3 Store
새로운 URI를 생성하지 않으며, 처음에 resource를 등록할 때 client가 전달한 key를 이용한다. 복수형 단어를 사용한다.
http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists
2.4 Contoller
Controller Resource Model은 절차 컨셉을 모델로 한다. Controller Resource는 Client에서 서버의 실행 가능한 function을 의미하는것과 같다.
Controller resources are like executable functions, with parameters and return values; inputs, and outputs.
Use “verb” to denote controller archetype.
RESTFUL 네이밍 가이드(https://restfulapi.net/resource-naming)에서는 Controller의 경우 resource를 조작하는것이 아닌 직접 function을 실행하는 행위를 나타내기위해 사용하므로, 동사를 사용해도 무방하다고 설명한다.
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play3. REST API 설계
3.1 동사가 아닌 명사로 Resource를 표현하자
RESTful URI는 동사가 아니라 명사 구성하는 것을 추천한다. 이유는 명사는 해당 Resource의 속성을 표현할 수 있지만 동사는 그렇지 못하기때문이다.
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}
3.2 소문자를 사용한다.
주소에서 대소문자를 구분하므로, 카멜방식이 아닌 소문자를 사용하여 작성한다.
// Bad
http://restapi.example.com/users/postComments
// Good
http://restapi.example.com/users/post-comments
* 카멜표기법:
이른바 낙타표기법은 말그대로 낙타의 등모습을 닮았다.
카멜표기법은 기본적으로 변수명을 모두 소문자로 쓴다.
다만 여러 단어가 이어지는 경우 첫단어를 제외하고 각 단어의 첫글자만 대문자로 지정해 주는 방식이다.
integer type의 변수를 예시로 보면,
int myFirstVariable;
방금 선언한 변수는 세단어로 되어있다. my, first, variable
모두 소문자로 작성하되, 첫단어를 제외한 각 단어의 첫글자를 대문자로 사용한다.
즉 my를 제외한 first와 variable의 첫단어만을 바꿔주는 표기법!
3.3 언더바(_)를 대신 하이픈(-)을 사용한다.
가급적 하이픈(-)의 사용도 최소화하며, 정확한 의미나 표현을 위해 단어의 결합이 불가피한 경우에 사용한다.
// Bad
http://restapi.example.com/users/post_comments
// Good
http://restapi.example.com/users/post-comments
3.4 마지막에 슬래시를 포함하지 않는다.
슬래시는 계층을 구분하는 것으로, 마지막에는 사용하지 않는다.
// Bad
http://restapi.example.com/users/
// Good
http://restapi.example.com/users
3.5 행위는 포함하지 않는다.
행위는 URL에 포함하지않고, HTTP Method를 사용하여 전달한다. (GET, POST, PUT, DELETE 등)
// Bad
POST http://restapi.example.com/users/1/delete-post/1
// Good
DELETE http://restapi.example.com/users/1/posts/1
3.6 파일 확장자는 URI에 포함시키지 않는다.
REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. Accept Header를 사용하도록 한다.
// Bad
http://restapi.example.com/users/photo.jpg
// Good
GET http://restapi.example.com/users/photo
HTTP/1.1 Host: restapi.example.com Accept: image/jpg
3.7 가급적 전달하고자하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다.
// Bad
http://restapi.example.com/posts/duplicating
// Good
http://restapi.example.com/posts/duplicate4. REST API Sample
카카오 기업의 OPEN API를 사례로 REST API Sample URL을 몇가지 소개한다.
* 카카오 REST API 레퍼런스: https://developers.kakao.com/docs/latest/ko/reference/rest-api-reference
| URL | Method | 기능 |
| /oauth/authorize | GET | 인가 코드 받기 |
| /oauth/token | POST | 토큰 받기, 토큰 갱신하기 |
| /v1/api/talk/profile | GET | 프로필 가져오기 |
| /v2/api/talk/memo/default/send | POST | 나에게 기본 템플릿으로 메시지 보내기 |
| /v1/api/story/post/note | POST | 글 스토리 쓰기 |
| /v1/api/story/delete/mystory | DELETE | 내 스토리 삭제하기 |
| /v1/payment/approve | POST | 단건 결제 승인 |
| /v1/payment/cancel | POST | 결제 취소 |
| /v1/payment/order | POST | 주문 조회 |
| /v1/payment/manage/subscription/status | POST | 정기 결제 상태 조회 |
참조
https://restfulapi.net/resource-naming/
P.S. SOAP과 REST 비교: https://server-engineer.tistory.com/737
댓글