Rest한 API URL을 만들어보자

우선 좋은 네이밍 패턴은

1) 언더바 대신 하이픈(-)을 사용한다. 대신 이 하이픈은 가독성을 높이기 위해서 사용해야 한다.

http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

2) 행위를 표현하지 않는다. 행위는 URL대신 메서드로 표현한다.

❌ users/posts/1 -(post)
⭕ users/1 -(put)

3) 파일 확장자는 URL에 포함하지 않는다.
4) 전달하고자 하는 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 사용한다.

❌ /course/writing
⭕ /course/write

POST /courses/{id}/publish     # 강좌 출판하기
POST /calculator/calculate    # 계산 실행
POST /users/login            # 로그인
POST /users/logout           # 로그아웃
POST /orders/{id}/cancel     # 주문 취소
POST /payments/{id}/refund   # 환불 처리

이런것처럼 단순히 리소스의 CRUD가 아니라, 특별한 비즈니스 프로세스나 작업을 수행해서 상태 변경이나 계산을 할 때 사용한다.

5) URL은 복수로 작성한다. 문법적으로 단수가 맞아도, 일관성이 더 중요하다. People처럼 단수/복수 둘다 가능한 경우, 어떻게 리소스를 작성해야할까? 이런 고민이 불필요한 오버헤드가 될 수 있다. 그렇기에 일관적으로 복수형을 사용해라.

http://api.college.com/students/3248234/courses - Retrieves a list of all courses that are learned by a student with id 3248234.
http://api.college.com/students/3248234/courses/physics - Retrieves course physics for a student with id 3248234.

관계를 표현할 땐 위처럼 계층적인 구조를 사용해라. 학생이 여러개의 course를 갖고 있고, 그 course는 학생에게 맵핑된다.

6) 마지막 끝에 /를 추가하지 말아라
(많은 프레임워크들이 write/와 write를 동일하게 처리하지만, rest한 api는 url이 다르면 다르다고 취급을 해야 한다. /를 붙이게 되면 모호함이 늘어나고, 혼란만 야기할 수 있다)

7)대문자 말고 소문자를 써라
(RFC 3986에 따르면 scheme과 host를 제외한 부분은 대소문자를 구분하기 때문에, 대문자 사용이 문제를 일으킬 수 있다)

원칙들에 따라서 API URL을 변경해봤다.
우선, 계층형 구조로 작성했고 crud외의 작동이라면 동사로 표현해봤다.

참고

7 Rules for REST API URI Design