HTTP API 설계 Best Practices (Restful, REST API)

Use nouns to represent resources

RESTful URI는 리소스를 언급해야 되며, 행동을 언급해서는 안된다. 예를 들면 다음과 같다.

• Users of the system
• User Accounts
• Network Devices etc.

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}

 

더 명백하게 리소스 아키타입을 4가지 카테고리 분류하자.(document, collection, store, and controller). 그러면 네이밍 컨벤션을 일관성있게 가져갈 수 있다. 

document

도큐먼트 리소스는 개체 인스턴스 또는 데이터베이스 레코드와 유사한 단수 개념이다. 도큐먼트의 상태 표현에는 필드와 값, 그리고 다른 리소스와의 관계를 다 포함한다. 도큐먼트 유형을 나타낼때에는 단수를 사용하자.

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

 

collection 

컬렉션 리소스는 서버가 관리하는 리소스의 디렉토리이다.
클라이언트는 컬렉션에 추가할 새로운 리소스를 제안할 수 있으나 새 리소스를 만들지 여부를 선택하는 것은 컬렉션 리소스에 달려 있습니다. 컬렉션 리소스는 포함하려는 항목을 선택하고 포함된 각 리소스의 URI도 결정한다. 컬렉션 리소스 유형을 나타낼때에는 복수를 사용하자.

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts

 

store

스토어는 클라이언트가 관리하는 리소스 리파지토리이다.  클라이언트가 어떠한 곡을 자신의 playlists 에 넣어서 관리하고 싶을 때, put, delete 등의 요청을 보내어, playlists에 추가하거나 제거하거나 할 수 있다. 스토어은 새로운 URI를 생성하지 않는 대신에 각 저장된 리소스는 URI를 가진다. URI는 스토어에 리소스를 처음 넣었을때 클라이언트에 의해 선택되었다.스토어 리소스 유형을 표현할때는 복수를 사용하자.

http://api.example.com/song-management/users/{id}/playlists

 

controller

컨트롤러 리소스는 실행 개념의 모델이다. 컨트롤러 리소스는 실행될 수 있는 함수이며, 파라미터와 리턴값, 입력과 출력을 가질 수 있다. 컨트롤러 유형을 언급할때는 동사를 사용하자.

http://api.example.com/song-management/users/{id}/playlist/play
http://api.example.com/cart-management/users/{id}/cart/checkout

 

Consistency is the key

최대 가독성과 유지보수성과 최소한의 혼란을 유지하기 위해 일관된 리소스 네이밍 컨벤션을 사용하자. 아래는 일관성을 얻기 위한 디자인 힌트이다.

Use forward slash (/) to indicate hierarchical relationships

/는 계층 구조를 표현하기 위해 사용된다.

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}

 

Do not use trailing forward slash (/) in URIs

URI 패스 마지막의 /는 아무런 의미가 없고 혼동만 온다. URI에서는 마지막에 /을 사용하지 말자.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices  /*This is much better version*/

 

Use hyphens (-) to improve the readability of URIs

가독성을 위해서 - 을 사용하기. 긴 문자열이나, 읽히기 어려운 문자열에 대하여 - 처리를 하여 가독성을 높이는 것을 고려해볼 수 있다.

http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices    /*This is much better version*/

 

Do not use underscores ( _ )

언더스코어를 사용하는 대신에 하이픈을 사용하자.  밑줄(_) 문자는 폰트영향으로 일부 브라우저나 화면에서 부분적으로 가려지거나 완전히 숨겨질 수 있기 때문이다. 혼동을 피하기 위해서 언더스코어(_) 대신에 하이픈(-)을 사용하자.

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  //Less readable

 

URI에는 소문자만 사용하자.

편리하고 일관성을 위해 URI 패스에는 소문자만 사용하자.

http://api.example.org/my-folder/my-doc       //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc     //2
http://api.example.org/My-Folder/my-doc       //3

 

Array를 표현하기 위해서 콤마(,)를 사용하자.

종종 다건의 리소스를 조회하거나 삭제 처리를 할 경우가 발생한다. 이 경우는 ,(comma)릴 이용해 복수의 id를 array로 전달한다.

GET http://api.example.com/device-management/managed-devices?ids={id1,id2,id3}  //Get multiple devices
DELETE http://api.example.com/device-management/managed-devices?ids={id1,id2,id3}  //Delete multiple devices

 

Do not use file extensions

파일 확장자를 사용하는 것은 아무런 이득이 없고 나빠보인다. URI길이를 줄이기 위해 제거하자. 유지할 이유가 없다. 위와 같은 이유와 별개로 파일 확장자를 사용하여 API의 미디어 유형을 강조하려면 Content-Type 헤더를 통해 전달되는 미디어 유형에 사용하여 본문의 콘텐츠를 처리하는 방법을 결정해야 합니다

http://api.example.com/device-management/managed-devices.xml  /*Do not use it*/
http://api.example.com/device-management/managed-devices    /*This is correct URI*/

 

Never use CRUD function names in URIs

CRUD 기능을 표현하기 위해 URI를 사용하지 말자. URI는 자원에 대한 어떠한 행동을 나타내는 것이 되어서는 안되고, 자원을 독립적으로 식별하는 방식으로 사용되어야 한다. HTTP 리퀘스트 메소드를 활용하여 CRUD 행동이 수행됨을 표시할 수 있다.

GET http://api.example.com/device-management/managed-devices  //Get all devices
POST http://api.example.com/device-management/managed-devices  //Create new Device
 
GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id

 Use query component to filter URI collection

종종 리소스를 정렬하거나, 필터하거나 객수를 제한할 필요가 있다.이러한 요구사항을 위해 새로운 API를 만드는 대신에 컬렉션 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/ 

REST API URI Naming Conventions and Best Practices