지난 포스팅에서 REST API에 대해서 알아보았는데 REST API를 작성할 때에도
그에 따른 규칙들이 있습니다.
여러 사람들과 협업을 해야하는 개발자들의 입장에서는 규칙을 잘 지켜서 서로 원활하게 소통하는 것이 중요하겠습니다.
URL 설계 시 규칙
1. / 의 쓰임새
슬래시 구분자 ' / '는 계층 관계를 나타낼 때 사용합니다.
ex) http://www.zoo/animals/dogs/john
위의 사이트에서 'john'이라는 개의 정보를 찾을 때 zoo -> animals -> dogs -> john
zoo 로부터 하위 소속들을 거쳐서 도달하는 구조입니다.
그렇기 때문에 URL 마지막 문자로 ' / '를 포함하지 않습니다.
2. resource간의 관계 표현
URL을 이루는 resource들은 동사보다는 명사로 이루어져야 합니다.
ex) GET : /users/{userid}/devices
리소스 간에는 연관 관계가 있을 수 있고 이런 경우 위와 같이 사용합니다.
3. URL에서는 '_'(언더바) 보다는 '-'(하이픈)을 권장
가독성이 중요한 '_'은 resource 해석하는 데 혼란을 줄 수 있기 때문입니다.
4. URL 경로에는 소문자가 적합
URL 경로에 대문자 사용은 피하도록 합니다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다.
5. 파일 확장자에 URL에 포함시키지 않음
ex) http://restapi.example.com/members/soccer/345/photo.jpg
REST API 에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URL안에 포함하지 않습니다.
규칙에 어긋나는 URL 예시
-
[GET]
http://localhost:8000/product/main_page_product- url은 page 기준이 아닌 resource 기준으로 작성합니다.
- 메인 페이지에 표출되어야할 정보가 무엇인지 판별하여 url을 정합니다.
- 한 번에 여러 종류의 정보를 표출해야 되는 경우는 프론트엔드 개발자와 협의하여 REST에 맞춰 두가지 이상의 endpoint를 동시에 호출합니다.
-
[GET]
http://localhost:8000/store/find_store- 동사 (find) 를 사용하지 않습니다.
-
[POST]
http://localhost:8000/product/add_first_item_information?name='자켓'&category='의류'- 자원을 추가 (add) 할 때는 ~/post 만으로 충분합니다.
-
[GET]
http://localhost:8000/store?name='강남'- 검색 기능은 자원의 정보를 호출하는 기능이므로 [GET] method를 사용합니다.
- 검색 키워드는 body를 통해 전달하지 않고, query string을 활용합니다.
