1. RESTful API
앞서 알아본 REST의 원칙을 지킨 RESTful API를 작성하기위한 네이밍 원칙을 알아보자
2. Resource 란 ?
REST에서의 기본적인 데이터 표현으로 URI를 통해 식별할 수 있는 모든 것을 말한다.
1) URI
웹 기술에서 사용하는 논리적 또는 물리적 리소스를 식별하는 고유한 문자 시퀀스
💡 쉽게 리소스를 식별하기 위한 방법이라고 생각하자.
2) 단일 리소스와 컬렉션 리소스
리소스는 단일 또는 컬렉션 리소스일 수 있다.
📌 예시
posts는 게시글 집합에 대한 컬랙션 리소스이고
post는 게시글 하나에 대한 단일 리소스일 때,
/posts표현을 통해 게시글 집합 리소스posts를 식별할 수 있고
/posts/{post_id}표현을 통해 게시글 하나에 대한 리소스post를 식별할 수 있다.
3) 하위 컬렉션 리소스
리소스는 하위 컬렉션 리소스를 포함할 수 있다.
📌 예시
게시글에 여러개의 해시태그가 존재한다고 해보자.이때 해시태그 집합 리소스(
hashtags)은 게시글의 하위 컬렉션으로posts/{post_id}/hashtags로 식별할 수 있다.
특정 해시태그 하나에 대한 단일 리소스(hashtag)는posts/{post_id}/hashtags/{hashtag_id}로 식별할 수 있다.
3. Resource Naming Guide
자 그럼 RESTful API를 작성하기위한 Resource의 표현 (URI)은 구체적으로 어떻게 해야할지 알아보자.
1) 명사를 사용하자
URI는 리소스(객체)를 식별하는 것이지 행위(동작)를 나타내는 것이 아니다. 행위는 Method로 표현한다.
ex) 게시글 생성 : 게시글 (리소스 - URI) / 생성 (행위 - Method)
따라서 리소스의 범주에 따라 일관성 있게 작성해야한다.
1-1) 문서 (document)
단일 리소스, 단수로 표현
ex) 게시글 하나, 유저 한명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
1-2) 컬렉션 (collection)
서버가 관리하는 리소스, 복수로 표현
ex) 유저 집합http://api.example.com/device-management/managed-devices http://api.example.com/user-management/users http://api.example.com/user-management/users/{id}/accounts
1-3) 저장소 (store)
클라이언트가 관리하는 리소스, 복수로 표현
ex) 노래리스트 (유저가 추가하거나 삭제할 수 있음)http://api.example.com/song-management/users/{id}/playlists
1-4) 컨트롤러 (controller)
그외 동작 리소스, 동사로 직접 표현
ex) 노래리스트 플레이 (method로 표현하기 힘듬)http://api.example.com/cart-management/users/{id}/cart/checkout http://api.example.com/song-management/users/{id}/playlist/play
2) 일관성이 핵심
일관성 있는 리소스 명명 규칙과 URI 형식을 사용하면 모호성을 최소화하고 가독성과 유지 관리 가능성을 최대화할 수 있다.
2-1) 슬래시(/)를 사용하여 계층 관계 나타내기
http://api.example.com/device-management http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices/{id} http://api.example.com/device-management/managed-devices/{id}/scripts http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
2-2) URI 끝에 슬래시(/)를 붙이지 않기
URI 경로 내의 마지막 문자인 슬래시(/)는 의미 값을 추가하지 않으며 혼동을 줄 수 있다.
http://api.example.com/device-management/managed-devices/ (bad case) http://api.example.com/device-management/managed-devices (good case)
2-3) 하이픈(-)을 사용하여 URI 가독성 향상
URI를 쉽게 해석할 수 있도록 하이픈(-) 문자를 사용하여 긴 경로 세그먼트에서 이름의 가독성을 향상시킬 수 있다.
2-4) 밑줄( _ )을 사용하지 않기
구분 기호로 하이픈 대신 밑줄을 사용하면 응용 프로그램의 글꼴에 따라 밑줄(_) 문자가 일부 브라우저나 화면에서 부분적으로 가려지거나 완전히 숨겨질 수 있습니다.
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location (good case) http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation (bad case) http://api.example.com/inventory-management/managed_entities/{id}/install_script_location (bad case)
2-5) URI에 소문자 사용
http://api.example.org/my-folder/my-doc (good case) HTTP://API.EXAMPLE.ORG/my-folder/my-doc (bad case) http://api.example.org/My-Folder/my-doc (bad case)
3) 파일 확장자를 사용하지 않기
http://api.example.com/device-management/managed-devices.xml (bad case) http://api.example.com/device-management/managed-devices (good case)
4) CRUD 함수 이름을 사용하지 않기
URI는 리소스를 고유하게 식별하는 데만 사용해야 하며 리소스에 대한 행위는 나타내지 않는다.
CRUD 기능은 HTTP request Method 통해 나타낸다.HTTP GET http://api.example.com/device-management/managed-devices //Get all devices HTTP POST http://api.example.com/device-management/managed-devices //Create new Device HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id
5) URI를 필터링하기위해서는 쿼리 파라미터를 사용하자
컬렉션 리소스를 정렬, 필터링할 때에는 새로운 API를 만들지 말고 쿼리파라미터를 사용한다.
http://api.example.com/device-management/managed-devices http://api.example.com/device-management/managed-devices?region=USA http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
참고
https://restfulapi.net/resource-naming/
https://en.wikipedia.org/wiki/Uniform_Resource_NameRESTful API 구현 코드 : https://github.com/kimphysicsman/PreOnBoarding_Service
