명세서를 처음 작성해봐서 무엇부터 적어야하나 고민이 많았다.
와이어프레임을 보고 API가 필요할 것 같은 것들을 적어보는데 어디서부터 어디까지 적어야하는지도 감이 안온다.
작성하면서 느낀거지만 이럴때는 그냥 적어보고 아니면 지우고 더 필요하면 추가하는 된다는 마인드만 있으면 된다.
1. API 명세서란?
- API(애플리케이션 프로그래밍 인터페이스)의 기능, 동작 방식, 사용법을 상세하게 기술한 문서를 의미한다.
- 꼭 들어가야 할 것
- API Path
- REST API 작성하는 법을 따라 URI를 만들면 된다.
- Method
- GET, POST, PATCH, DELETE로 데이터를 가져오는지 바꾸는지 등을 알 수 있다.
- 내가 이해한 바로는
- GET : 무언가를 불러올 때 사용
- POST : 무언가를 생성할 때 사용
- PATCH : 무언가를 변경할 때 사용
- DELETE : 무언가를 삭제할 때 사용
- Request Body / Query Parameter
- Request Body
- Method로 POST를 사용할 때 많이쓰며 사용자가 보내는 데이터들을 body로 전달해 URL에 보이지 않게한다.
- Query Parameter
- Method로 GET를 사용할 때 주로 쓰며 사용자가 보내는 데이터를 URL 창에서 보이게 전달된다.
- Request Body
- Response Body
- 서버에서 유저에게 전달하는데이터
- HTTP 응답 코드를 같이 보내면 프론트엔드에서 상태를 알기 쉬움
- API Path
- 주로 Request Body / Query Parameter, Response Body
2. HTTP 상태코드
HTTP 응답 상태 코드는 특정 HTTP 요청이 성공적으로 완료되었는지 알려준다.
응답은 5개의 그룹으로 나눠진다.
- 1XX: Informational(정보 제공)
- 임시 응답으로 현재 클라이언트의 요청까지는 처리되었으니 계속 진행하라는 의미
- 2XX: Success(성공)
- 클라이언트의 요청이 서버에서 성공적으로 처리되었다는 의미
- 3XX: Redirection(리다이렉션)
- 완전한 처리를 위해서 추가 동작이 필요한 경우
- 주로 서버의 주소 또는 요청한 URI의 웹 문서가 이동되었으니 그 주소로 다시 시도하라는 의미
- 4XX: Client Error(클라이언트 에러)
- 없는 페이지를 요청하는 등 클라이언트의 요청 메세지 내용이 잘못된 경우를 의미
- 없는 페이지를 요청하는 등 클라이언트의 요청 메세지 내용이 잘못된 경우를 의미
- 5XX: Server Error(서버 에러)
- 서버 사정으로 메시지 처리에 문제가 발생한 경우
- 서버의 부하, DB 처리 과정 오류, 서버에서 익셉션이 발생하는 경우를 의미
참고
https://developer.mozilla.org/ko/docs/Web/HTTP/Reference/Status