[Spring] REST API - URI 디자인 가이드

 

ㅁ 개요

 SOAP과 REST 비교에 관한 글을 작성하였고, 이번 글은 간결한 URI에 대해서 정리하였다. 이전 글을 읽어보면 REST API의 핵심은 간결성이며, 그 간결성을 통한 궁극적인 통신 속도에 최적화이다. 다시 정리하여 말하자면, SOAP(Simple Object Access Protocol)는 그 자체로 프로토콜이며, 보안이나 메시지 전송 등에 있어서 REST보다 더 많은 표준들로 정의되어 보안을 강조하는 금융권에서 사용하고, REST는 아키텍처 스타일로 기업들에서 애플리에이션 서버에 접속할 수 있는 도구로서 빠른 속도와 수정의 용이성으로 인해 빠르게 시장의 요구를 수용할 수 있다.

 

ㅁ REST API의 탄생

  REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 ( Roy Fielding)의 박사학위 논문에서 최초로 소개되었습니다. 로이 필딩은 HTTP/1.0, 1.1 스펙 작성에 참여했었고 아파치 HTTP 서버 프로젝트의 공동설립자이기도 합니다. 그는 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용하지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 REST 아키텍처를 발표했다.

 

 

ㅁ REST 구성

 1) URI은 정보의 자원을 표현하며 명사를 주로 사용한다.
    사실 URI(uniform resource identifier) 자체가  통합 자원 식별자라는 의미를 가지고 있다.

 2) 자원에 대한 행위(GET, POST, PUT, DELETE)를 HTTP Method로 정의한다.

 

참고로, URI와 URL을 혼용하는데, URL(통합 자원 지시자, uniform resource locator)은 URI의 가장 흔한 형태이다.
단순하게 말하자면, URI는 규약이고, URL은 그 규약에 대한 한 형태이다. 수학적으로 말하자면 URL은 URI의 부분집합인 것이다.

 

예시로,

GET /members/delete/1

URI상에 delete라는 동사는 적절하지 않다. 동사는 Get으로 표현하고 URI은 명사, 자원을 명확히 표현해야한다.

회원의 정보를 가져오는 GET과 삭제를 의미하는 Delete가 함께 있어 URI자체로 명확한 목적을 이해할 수 없다.

 

DELETE /members/1

 삭제의 경우는  자원(member 중 1번)을 Delete 한다. URI을 통해 명확한 목적을 표현할 수 있다.

 

GET /members/1

 조회의 경우 자원(member 중 1번)을 GET 한다.

 

POST /members/2  

 추가의 경우 자원(members 중 2번)을 Post로 표현한다.

 

정리하자면, POST, GET, PUT, DELETE 라는  4가지의 Method로 CRUD를 할 수 있다.

 

METHOD	역할
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
GET	GET를 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	PUT를 통해 해당 리소스를 수정한다.
DELETE	DELETE를 통해 리소스를 삭제한다.

 

 

ㅁ REST API  URI 규칙

1. 슬래시(/)를 사용하여 계층적 관계를 나타낸다. 

http://api.canvas.com/shapes/polygons/quadrilaterals/squares

슬래시 문자는 리소스 간의 계층적 관계를 나타내는 구조로 설계된다.

 

 

2. URI 마지막에 슬래시(/)를 포함하지 않는다.

http://api.canvas.com/shapes/    : X
http://api.canvas.com/shapes     : O

URI의 마지막에는 자원의 형태로 끝나야 한다. 마지막의 /은 자원을 표현하지 않기에 불필요하다.

 

 

3. URI는 소문자로 작성한다.

RFC 3986은 URI를 scheme 혹은 host component를 제외하고 대소문자를 구분하는 것으로 정의하였습니다.

하지만 모든 시스템이 대소문자를 구별하는 것이 아니다. 따라서 시스템에 혼선의 여지가 있기 때문에 소문자를 사용한다.

- http://rest.api/thisIsMyPost
- http://rest.api/thisismypost

 소문자만을 공백없이 표현할 때에 가독성의 문제가 발생한다. 이를 해결하기 위해 하이픈(-)을 활용한다.

 

 

4.URI 가독성을 높이기 위해 하이픈(-)을 사용하고 반대로 밑줄(_)을 사용하지 않는다.

URI의 가독성을 높이기 위해 하이픈(-)을 사용한다. URI자체에 공백을 사용할 수 없기 때문에 공백을 하이픈으로 대체한다.

http://api.example.com/rest/api/this-is-uri-design

한편 가독성을 위해서 _을 사용하면 안된다.

http://api.example.com/rest/api/this_is_uri_design
http://api.example.com/rest/api/this_is_uri_design

  위의 두 URI은 같다. 하지만 하이퍼표시가 되면 밑줄(_)을 구분할 수 없다.

 

 

5. 마침표(.) 문자를 사용하지 않는다.

마침표(.) 문자는 일반적으로 파일 확장자를 의미한다. URI에는 파일 확장자를 포함해서는 안되고,

ex)
X : http://restapi.example.com/members/soccer/345/photo.jpg
O : http://restapi.example.com/members/soccer/345/photo

 

GET /members/soccer/345/photo HTTP/1.1 
Host: restapi.example.com 
Accept: image/jpg

확장자는 대신 헤더를 이용하여 컨텐츠를 처리하면, 서버가 형식에 맞춰 보내준다.

 

 

ㅁ 함께 보면 좋은 사이트

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

7 Rules for REST API URI Design

 

URI vs URL vs URN :: 마이구미

 

SOAP REST 차이, 두 방식의 가장 큰 차이점은? - wishket