[RSET API] RESTIful한 URL 설계

1. REST API란?

• Representational State Transfer
• REST API란 REST Architecture의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스를 뜻한다.
• 즉, 자원을 이름(자원의 표현)으로 표현하고 자원의 상태(정보)를 주고 받는 것을 의미한다.
• REST는 URI를 통해 자원을 표시하고 HTTP Method를 이용하여 해당 자원의 행위를 정해주며 그 결과를 받는 것을 말한다.

2. REST의 구성요소

REST는 자원, 행위, 표현으로 구성된다.

• 자원(Resource)는 URI가 가리키는 리소스
• 행위(Verb)는 HTTP Method (ex. GET/ POST/ PUT/ DELETE 등..)
• 표현(Representation)은 리소스의 특정 시점 상태를 반영하고 있는 정보

3. REST API URI 작성 규칙

API에는 어떻게 이름을 붙여야 할까?

• 보통의 경우에 api/버전/Resource 의 형태로 사용한다.

자원(Resource) 앞에 /api/버전 를 붙이는 것이 뭐가 좋을까?

기존에 API를 설계할 때, 단순히 엔드포인트/resource를 붙여서 사용해왔다. 하지만, 다른 개발자들의 git을 보면서 앞에 /api를 붙여서 사용하는 것을 보게 되면서 '앞에 /api가 무슨 의미가 있지?' 하는 생각이 들었다.

다른 사람들의 벨로그와 stackoverflow를 보면서 정리하자면

1. /api를 붙이면 url만 봐도 API라는 것을 알 수 있어서 편리하다.
2. 서버 자체가 웹 페이지를 가지는 경우 API 주소가 분리되는 것이 좋을 것이다.
3. /api/v1처럼 versioning을 하면 사용중이던 API의 버전을 바꾸어야할 때 용이하다.

생각해보니 맞는말만 써서 생각이 변하게 되었다. /api가 없을 경우 단순히 REST API인지 페이지 라우팅인지 헷갈릴수 있는 부분이었는데 이번 프로젝트를 하면서 /api를 붙여 사용하니 API주소가 분리되어 편리하였다.
물론 나같은 경우 서버 자체가 웹 페이지를 가지는 경우는 아니었지만 이러한 방식으로 사용하는 것이 더 좋았다. 또한, /api/ 뒤에 v1과 같은 버전을 붙이면서 어떻게 변경되었는지 알 수 있는 부분이었다.