지난주에 작성했던 기능명세서와 페이지기획서에 피드백을 반영하여 수정하여 제출하였다. 프로젝트를 시작하기에 앞서 한층 더 정돈된 느낌이 들었다.
이번 주차에는 API 명세서와 DB 명세서를 작성하였다. 작성해본 경험이 한번 있지만 기억이 잘 나지않아서 이전 기수의 작업물들을 참고하였다. DB 명세서는 빨리 끝낼 수 있었지만 API 명세서에서 Restful API에 대한 개념들을 다시 찾아보면서 하느라 시간이 조금 더 걸렸다. 우리 팀은 하나의 노션 페이지에 다 정리해두기로 했다.
API 명세서
1) URI는 정보의 자원을 표현해야 한다는 점
-> resource는 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
-> resource의 스토어 이름으로는 복수 명사를 사용해야 한다.
2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다는 점
-> HTTP Method나 동사표현이 URI에 들어가면 안됩니다.
-> :id와 같이 변하는 값은 하나의 특정 resource를 나타내는 고유값이어야 한다.
주로 쓰는 HTTP 메소드
GET: 조회 (받겠다)
POST: 리소스 생성 (보내겠다)
PUT: 리소스 전체 갱신(놓겠다/넣겠다)
PATCH: 리소스 부분 갱신(붙이겠다)
DELETE: 리소스 삭제 (지정한 서버의 파일을 삭제하겠다)
Rest API 세부규칙
1) 슬래시(/)는 계층 관계를 나타낸다.
http://www.example.com/fruits/banana
2) URI의 마지막엔 슬래시(/)를 포함하지 않는다.
http://www.example.com/fruits/banana/ (X)
3) 가독성을 높이기 위해 하이픈(-)을 사용할 수 있으나 언더바(_)를 사용하진 않는다.
http://www.example.com/tropical_fruits/banana/ (X)
http://www.example.com/tropical-fruits/banana/ (O)
4) URI 경로에는 소문자를 씁니다.
http://api.example.restapi.org/my-folder/my-doc (O)
HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc (O)
-> 호스트에서는 대소문자를 구별하지 않기 때문에 위의 두 URI는 같은 URI이다.
http://api.example.restapi.org/my-folder/my-doc
http://api.example.restapi.org/My-Folder/my-doc
-> 위의 두 URI는 다른 URI이다. 뒤에 붙는 path가 대소문자로 구분되기 때문.
(RFC 3986에 따르면 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정한다고 한다. 따라서 전부 소문자이거나 전부 대문자이면 괜찮지만, 일반적으로 대문자는 잘 쓰지 않기 때문에 소문자로 쓰는 것을 권함.)
5) 파일 확장자는 URI에 포함하지 않고 Accept header을 사용한다.
6) 리소스간 연관관계가 있는 경우
/리소스명/리소스ID/관계있는 다른 리소스명(일반적으로 소유has의 관계)
ex) GET /users/:id/skills
출처: https://devuna.tistory.com/79, https://one-it.tistory.com/entry/RESTful-API-%EC%84%A4%EA%B3%84-%EA%B7%9C%EC%B9%99