필자는 현재 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/play

3. 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/duplicate

4. 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/

https://developers.kakao.com/

 

출처: https://server-engineer.tistory.com/886 [임대리 개발일지:티스토리]

 

 

 

 

본 웹사이트는 광고를 포함하고 있습니다.
광고 클릭에서 발생하는 수익금은 모두 웹사이트 서버의 유지 및 관리, 그리고 기술 콘텐츠 향상을 위해 쓰여집니다.
번호 제목 글쓴이 날짜 조회 수
1088 [ 一日30分 인생승리의 학습법 ] Build Your Own Remote Desktop Application using Javascript, Python & WebRTC — Part 2 file 졸리운_곰 2022.08.05 5
1087 [ 一日30分 인생승리의 학습법 ] Build Your Own Remote Desktop Application using Javascript, Python & WebRTC — Part 1 file 졸리운_곰 2022.08.05 2
1086 [ 一日30分 인생승리의 학습법 ] REST API 규칙 졸리운_곰 2022.08.03 0
» [ 一日30分 인생승리의 학습법 ]REST API 설계 (네이밍) 졸리운_곰 2022.08.03 0
1084 [ 一日30分 인생승리의 학습법] [2탄!!] KrakenD Demo 면을 알아보죠! file 졸리운_곰 2022.08.01 0
1083 [ 一日30分 인생승리의 학습법] [1탄!!]KrakenD가 무엇인가? 과연 Api Gateway로 으뜸인가요? file 졸리운_곰 2022.08.01 0
1082 [ 一日30分 인생승리의 학습법] 오픈소스 라이선스 별 의무사항 졸리운_곰 2022.07.29 0
1081 [ 一日30分 인생승리의 학습법] The complete guide to (external) Domain Specific Languages file 졸리운_곰 2022.07.08 3
1080 [ 一日30分 인생승리의 학습법] [Elasticsearch] 기본 개념잡기 file 졸리운_곰 2022.06.02 7
1079 [ 一日30分 인생승리의 학습법]node - pm2로 node.js 프로세스 관리하기 - 기본 명령어, 실행하기 file 졸리운_곰 2022.05.28 3
1078 [ 一日30分 인생승리의 학습법][1탄!!]KrakenD가 무엇인가? 과연 Api Gateway로 으뜸인가요? file 졸리운_곰 2022.04.15 5
1077 [ 一日30分 인생승리의 학습법][API Gateway] Kong Gateway 설치 file 졸리운_곰 2022.04.15 3
1076 [ 一日30分 인생승리의 학습법] TeX_및_LaTeX_수식_문법 file 졸리운_곰 2022.03.19 23
1075 [ 一日30分 인생승리의 학습법] Visual Basic application on linux 졸리운_곰 2022.02.22 5
1074 [ 一日30分 인생승리의 학습법] Truffle을 이용한 DApp 개발환경 구성 file 졸리운_곰 2022.02.20 78
1073 [ 一日30分 인생승리의 학습법]LaTeX 활용해서 논문쓰장 file 졸리운_곰 2022.02.17 10
1072 [ 一日30分 인생승리의 학습법] LaTeX 초보자가 감을 잡는 것을 돕는 몇가지 팁 졸리운_곰 2022.02.17 7
1071 [ 一日30分 인생승리의 학습법] 수식 입력이 가능한 마인드맵 프로그램, 프리플레인(freeplane) file 졸리운_곰 2022.02.16 13
1070 [ 一日30分 인생승리의 학습법] Awesome Metaverse Awesome 짱!~ 메티버스 오픈소스 file 졸리운_곰 2022.02.13 4
1069 [ 一日30分 인생승리의 학습법] 제 NAS의 Docker 목록 file 졸리운_곰 2022.01.31 22
대표 김성준 주소 : 경기 용인 분당수지 U타워 등록번호 : 142-07-27414
통신판매업 신고 : 제2012-용인수지-0185호 출판업 신고 : 수지구청 제 123호 개인정보보호최고책임자 : 김성준 sjkim70@stechstar.com
대표전화 : 010-4589-2193 [fax] 02-6280-1294 COPYRIGHT(C) stechstar.com ALL RIGHTS RESERVED