Api 명세서와 협업

API 명세서

1. API 명세서란

   • API의 이름, 파라미터, 반환 값 등의 구문, 인증 및 인가 방법, 데이터 전달 형식 등 API를 정확하게 호출하고 그 결과를 병확히 해석하는데 필요한 정보들을 일관된 형식으로 기술한 것

2. 구성 요소

   1. 이름 및 설명

      

   2. 기본정보

      • Host 주소

      • Endpoing

      • HTTP Method

        • 'GET'은 지정된 URL에서 리소스의 표현을 검색, 응답 메시지의 본문은 요청된 리소스이 세부 정보 포함

        • 'POST'는 지정된 URL에 새 리소스를 만듬, 요청 메시지의 본문은 새 리소스의 세부 정보를 제공

        • 'PUT'은 지정된 URL에 리소스를 만들거나 대체, 요청 메시지의 본문을 만들 때 또는 업데이트할 때 리소스를 지정

        • 'PATCH' 리소스의 부분 업데이트 수행, 요청 본문은 리소스에 적용할 변경 내용을 지정

        • 'DELETE' 지정된 URL의 리소스를 제거

          

   3. Request

      • Header

      • Parameter

      • Body

        

   4. Response

      • Header

      • Body

        

3. 예제

   

4. API 명세서의 중요성

   • 표준화된 API 명세서는 개발자 간의 협업을 촉진하며, 외부 개발자가 소프트웨어를 쉽게 이해하고 활용할 수 있게 한다.

   • 정확하고 업데이트된 API 문서는 시스템의 에러를 빠르게 찾고 해결하는 데 도움이 된다.

5. 명세서 작성 시 고려사항

   • 정확성 : API의 작동 방식을 정확하게 기술해야 한다. API가 어떤 입력을 받고, 어떤 출력을 내는지, 그리고 가능한 애러 상황과 대응 방안을 포함해야 ㅎ나다.

   • 세부 설명 : API의 각 기능과 요청별 응답 예시를 포함해야 한다. 개발자가 예상하는 API의 동작 방식과 실제 동작 방식이 다르다면, 에러를 초래할 수 있다.

   • 일관성 : API 명세서는 정체적으로 일관성을 유지해야 한다. 동일한 정보나 구조를 여러 방식으로 표현하면, 개발자가 혼동할 수 있다.