RESTful API의 URL 작성 규칙

 

REST API란?

REST(Representational State Transfer)는 HTTP 네트워크 상의 리소스(Resource, 자원)를 정의하고 해당 리소스를 URI라는 고유한 주소로 접근하는 접근 방식을 의미하며, REST API란 REST 방식을 통해서 리소스에 접근하기 위한 서비스 API를 지칭합니다.

 

REST에서 의미하는 리소스란?

REST에서 의미하는 자원은 데이터베이스에 저장된 데이터, 문서, 이미지, 동영상 등 HTTP 통신을 통해 주고 받을 수 있는 모든 것을 의미합니다.

 

URI(Uniform Resource Identifier)와 URL(Uniform Resource Locator)

URI는 네트워크 상에 있는 특정 리소스를 식별하는 통합 자원 식별자(Uniform Resource Identifier)를 의미합니다.

URL은 인터넷에 있는 리소스를 나타내는 통합 리소스 식별자를 의미하며, 우리가 흔히들 이야기하는 웹 상의 주소를 의미합니다.

URI는 URL의 상위 개념으로 볼 수 있습니다.

URI는 리소스를 식별하는 식별자 역할을 하고, URL은 리소스의 위치를 가리킵니다. 

예) http://www.itivllage.tistory.com/manage? id = 1

위 예에서 'http://www.itivllage.tistory.com/manage'까지는 리소스의 위치를 가리키는 URL이라고 할 수 있고, 'http://www.itivllage.tistory.com/manage? id = 1'는 리소스를 식별하기 위한 'id = 1'이라는 고유 식별자 붙었으므로 URI라고 할 수 있습니다.

 

REST API URI 작성 규칙

그러면 이번에는 HTTP 상에서 REST API 서비스를 만드는 입장에서 REST API URI를 작성하는 규칙들을 살펴보도록 하겠습니다.

URI 작성 기본 규칙

• URI의 마지막이 '/'로 끝나지 않아야 합니다.
  • better
    • http://www.itivllage.tistory.com/coffees (ㅇ)
  • worse
    • http://www.itivllage.tistory.com/coffees/ (x)
• 동사 보다는 명사를 사용합니다.
  • better
    • http://www.itivllage.tistory.com/coffees (ㅇ)
  • worse
    • http://www.itivllage.tistory.com/coffees/update (x) 
• 단수형 보다는 복수형 명사를 사용합니다.
  • better
    • http://www.itivllage.tistory.com/coffees (ㅇ) 
  • worse
    • http://www.itivllage.tistory.com/coffee (x)
• URI는 기본 소문자로 사용합니다.
• 언더스코어( _ ) 대신에 하이픈(-)을 사용합니다.
• 파일 확장자는 URI에 포함하지 않습니다.

 

 

 

URI에서 리소스 간의 관계를 표현하는 방법

REST API를 작성하다보면 특정 리소스 간의 관계를 URI로 표현해야 할 경우가 굉장히 많습니다.

이해를 위해 예시를 살펴보도록 하겠습니다.

• 'http://www.itivllage.tistory.com/members'는 전체 회원에 대한 리소스를 의미합니다. 
• 'http://www.itivllage.tistory.com/members/1'는 1이라는 ID를 가지는 회원에 대한 리소스를 의미합니다.. 
• 'http://www.itivllage.tistory.com/members/1/orders'는 1이라는 ID를 가지는 회원의 주문에 대한 리소스를 의미합니다. 

 

 

 

더 읽을 거리

• https://docs.microsoft.com/ko-kr/azure/architecture/best-practices/api-design
• https://dzone.com/articles/7-rules-for-rest-api-uri-design-1
• https://ko.wikipedia.org/wiki/REST

REST - 위키백과, 우리 모두의 백과사전

7 Rules for REST API URI Design - DZone Integration

웹 API 디자인 모범 사례 - Azure Architecture Center