API 명세서 작성 tip

https://tech.kakaoenterprise.com/127

[TW] API 문서 톺아보기

정말 정말 좋은 글이다! 꼭 한 번씩 읽어보자
 
https://cobinding.tistory.com/165

[BackEnd] API 명세서 작성 가이드 라인 | 작성 예시

그리고 이 글을 요약하며 예시까지 추가한 글이다! 역시 읽어보자
 
 
 

당근마켓 API 인덱스 초고 예시

 
API 명세서는 API의 모든 기능과 그 사용 방법을 설명하는 문서이다. 이는 API를 사용하는 개발자가 API의 엔드포인트, 요청과 응답 형식, 데이터 유형, 인증 방법 등을 이해하고 올바르게 활용할 수 있도록 돕는다. 명세서가 없다면 API를 사용할 때 많은 시행착오와 시간이 소요될 수 있다. 따라서 API 명세서는 API의 설계도와도 같은 역할을 하며, 개발자가 쉽게 이해하고 활용할 수 있도록 구조화된 정보를 제공한다. 특히 API 명세서를 먼저 설계하지 않는다면, 프론트엔드 개발자는 API 개발이 완료될 때까지 삽집을 할 가능성이 있게 된다.
 
ㅇ상태 코드(Status Code): API 요청의 성공 여부
 

• 200 OK: 요청이 성공적으로 처리됨
• 201 Created: 새로운 리소스가 생성됨
• 204 No Content: 요청이 성공했으나 반환할 데이터가 없음
• 400 Bad Request: 잘못된 요청
• 401 Unauthorized: 인증 실패
• 404 Not Found: 요청한 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버 내부에서 오류가 발생하여 요청을 처리할 수 없음
• 503 Service Unavailable: 서버가 현재 요청을 처리할 수 없음을 나타냄 (e.g. 서버 과부하, 유지보수중, ...)

2xx : 성공
4xx : 클라이언트 측에서의 요청 오류
5xx : 서버 측에서의 요청 처리 오류
 
 
[장바구니 상품 추가에 대한 API 명세서 예시]

API 명세서만 보고도 사용할 수 있도록 만들자

 
(프론트엔드 개발자와의 협력 tip)
1. API 설계를 먼저 하자
프론트엔드 개발자는 API 규격을 보고 작업을 한다. 만약에 API 명세서가 나중에 나온다면 API 구현 기간 동안 API 호출 부분 작업을 하지 못하거나 임의로 API 주소, HTTP method, 속성명을 사용하다가 모두 다 바꿔야 하는 불상사가 생긴다!
 
2. API 설계를 할 때 소통하자
API를 사용하는 사람 입장을 고려하자! 네이밍, 반환타입, JSON 구조, 로직 적용 책임 분배(정렬을 서버에서 or 프론트에서 등)
 
3. API 업데이트를 사전에 공유하자
API 스펙이 변경되면 클라이언트 코드도 변경되어야 하므로, 업데이트할 내용을 사전에 공유하고 조율하는 과정이 필수적이다!
 
 
실무에서 이 케이스들을 지키지 못하는 경우가 생각보다 꽤 있다고 한다...

 
 
(참고)
API 문서화 및 테스트 툴: Swagger, Rest Docs, Postman, Notion
※ 내 친구는 개발 전에는 먼저 Notion으로 API 명세를 작성하고 FE 개발자한테 보여줄 때는 Swagger로 넘겨준다고 한다
 
보통 문서화는 Swagger vs Rest Docs 로 갈리고 테스트는 Postman 으로 한다
 
 
 
 
 
 
참고 및 출처: https://park-algorithm.tistory.com/entry/%EB%8B%B9%EA%B7%BC%EB%A7%88%EC%BC%93-API-%EC%84%A4%EA%B3%84%ED%95%98%EA%B8%B0-2%EC%9D%BC%EC%B0%A8, https://www.youtube.com/watch?v=r03ObslCNlo, https://www.youtube.com/watch?v=r03ObslCNlo

정말 정말 좋은 영상이다