본 문서는 REST-API의 Self-descriptiveness와 URI 설계에 대한 부분만을 명시하고 있다. 다른 REST적인 특징들은 본 문서에서 다루지 않는다.
API를 만들다 보면 주변에서 많이 들려오는 말이 있을 것이다. 'REST 하다. REST 하지 않다.' 이러한 말들을 처음 들었을 때는 무슨 의미인지 파악하기가 힘들었다. 'API면 API지 REST하지 않다라는 말은 왜 하는거지.'이러한 생각들이 사무칠 때 쯤 REST API를 만든 로이 필딩의 논문을 보았다.
로이 필딩은 2000년에 REST API 아키텍처를 박사 논문으로 만든 사람으로써, Web설계 우수성에 비해 제대로 사용되지 못하는 안타까움으로 만들었다고 한다.
API는 다음과 같은 요소를 가지고 있다.
1. 자원 (Resource)
2. 행위 (Verb)
3. 표현 (Representation of Resource)
이러한 구성 요소를 가지고 REST스러운 API를 design하는 특징은 다음과 같이 적혀져 있다.
- Uniform
- 인터페이스 일관성
- Stateless
- 무상태성
- Cacheable
- 캐시 처리 가능
- Self-descriptiveness
- 자체 표현 구조
- Client-Server
- Layer System
- Server에 대한 다계층 구조
API를 만들면서 가장 쉬우면서 지키기 어렵다고 생각한 부분은 Self-descriptiveness과 URI부분이었던 것 같다. 규칙을 지키기 가장 쉬우면서 가장 어려운 영역인 것 같았다. URI와 Self-descriptiveness의 규칙은 다음과 같다.
1. Self-descriptive 규척
- 메세지만 보고 명확해야 된다.
- 목적지가 명확해야 된다.
이러한 두개의 규칙이 주요 규칙이지만, 가장 많이 범하기 쉬운 규칙이다.
# Http 버전 명시와 성공이 되었을 때, 어떤한 코드로 오는지 명시가 되어야 된다.
GET HTTP/1.1 200 OK
# Client가 알기 위해선 목적지가 필요하다.
Host: https://www.example.com
# Body의 내용을 Client가 알아야 된다.
Content-Type: application/json
{ "data" : "test data" }위의 예제와 같이 보내질 경우 Self-descriptive하다 할 수 있다. Client가 API를 사용하기 위한 정보가 들어있기 때문이다.
Client가 API를 사용하기 위해선 API의 주소를 알아야 된다. 또한, body에 담긴 내용이 어떠한 형식으로 오는지도 명시를 해야 Client가 사용을 할 떄, 불편함이 없다.
2. URI 설계
uri설계를 할 때, 가장 많이 범할 수 있는 부분은 uri에 동적인 부분이 들어갈 수 있는 것이다.
GET /read/user/info위의 uri를 그대로 해석한다면 "user의 정보를 읽는 것을 가진다." 굉장히 어색하고, 불편한 uri이다. 심지어 읽기에도 불편하다. 당연히 동사가 두 번이나 들어가 있어서 읽기 불편한 요소가 된다.
GET /user/info위의 uri를 해석하면 "user의 정보를 가져온다"가 된다. 보기만해도 어떠한 uri를 가지고 있는지 확실히 알 수 있어서 보기에도 좋다.
정리
uri 설계와 REST API를 설계할 떄, 많은 범용적인 실수와 당연한 것들에 대한 무시가 남무한다. 이러한 API는 REST하지 않다라고 말을 한다. 요즘에 나오는 대부분의 API들은 이러한 규칙을 지키지 않는다. 사실 만들고 나서 "우리만의 REST 규칙을 만든 것이다." 라고 하면 따질 말이 없지만, 그 전에 기본에 충실한 것이 가장 중요한 것이 아닐까란 생각이 든다.
