API 명세서

개요

딥러닝 모델 학습 관리, 기타 잡다한 연구 및 연구 문서 등을 작성하던 내 업무에서 처음 API를 만들어야 하는 업무가 들어왔다.
AI 모델 서빙을 하는 API를 만들어야하는데 내가 지금까지 했던 여러 경험들에 의하면 명세 - 설계 - 개발 의 과정에서 시작은 탄탄하게 하지 못하면 무너지는 경우가 많았다.

API 명세를 하기 위해서 무엇을 해야하고 가장 스탠다드한 형태가 무엇인지 한번 알아보자

API 명세란

API는 컴퓨터와 프로그램 간의 연결이라고 정의된다.
API는 정의 및 프로토콜 집합을 사용해서 두 소프트웨어 구성 요소가 서로 통신할 수 있게끔 하는 매커니즘 이다.

Application Programming Interface 의 줄임말. API의 맥락에서 애플리케이션이라는 단어는 고유한 기능을 가진 모든 소프트웨어를 나타낸다.
인터페이스는 두 어플리케이션 간의 서비스 계약

API 문서에는 개발자 어떤 요청을 하면 어떤 응답을 전달하는지에 대한 프로그램 간의 계약서라고 생각하면 된다.

백엔드는 API문서가 잇어야 기능을 정의하고 작업 할 수 있고 프론트엔드를 이를 바타응로 백엔드에서 어떤 값이 올지 알고 작업 할 수 있다.

AI 명세서 작성법

내가 개발해야하는 것을 AI 모델에 대한 추론 결과를 반환하는 API 서버를 만들어야한다.
입력 대부분은 이미지가 되고 이미지를 어떻게 입력으로 주는지를 조사해야하고
전처리, 후처리 후 정말 추론에 대한 결과만 전달해야하는 상황이다.
이때 입력과 출력에 필요한 스펙을 정리해서 명세할 예정이다.

필수 요소

• 1. API 개요

  API를 간단하게 설명하는 섹션
  어떤 용도인지 어떤 유형의 API인지 어떤 용청 방식인지를 설명

• 2.

  API에 대한 각 엔드포인트에 대한 설명을 포함
  각 엔드포인트는 API의 특정 동작을 수행하며, 일반적으로 HTTP 메소드 를 사용해서 호출
  각 엔드포인트의 URL과 함께 해당 엔드포인트에서 수행되는 동작을 설명

• 3. 매개변수 & Request Body

  API 호출시 전달되는 매개변수와 요청 바디에 대한 설명
  각 매개변수에 대한 설명 및 데이터 타입, 값 등 명시

• 4. 응답(Response)

• 5. Example

• 6. Error 처리 설명

• 7. 자원 모델 설명

사실 명세서와 API Document의 명확한 차이점을 아직 잘 모르겠다.
하지만 API Doc에서도 위에 필수 요소라고 명시된 부분을 잘 명시하고 있다.

내가 조사한 두가지 형태의 문서를 모두 정리하며 현재 내 상황에 잘 맞고 추후 보게될 다음 개발자가 이해하기 쉬운 형태로 문서를 정리해보려한다.

Case 1

하나씩 살펴보자
API title : 해당 API의 이름이다 (login,logout)
URL : API 경로 즉 엔드포인트를 의미한다.
Method : GET,POST,PUT,DELETE (CRUD)를 의미
URL Params : URL을 통해서 값을 넘길경우를 의미한다.
Success Response : 정상 응답시 받은 스테이스코드 와 반환 값
Error Response : 오류 응답시 받은 스테이스 코드오 ㅏ반환 값
Sample Call : 예시

Case 2

주로 POST 메소드를 통한 제공된 추론 결과를 조회하는 경우이기 때문에 예시로 조회로 설정한다.

• Request

  curl -X GET https://{SERVER_URL}/api/posts?page=1&size=10 \
  -H "Authorization: Bearer {API_KEY}"

  GET http://서버 URL/api/posts

• Request Header
  헤더가 있는 경우

  파라미터	타입	필수	설명
  Authorization	String	필수	인증키

• Request Elements
  전달해야하는 인자값 정보

  파라미터	타입	필수	설명
  page	Integer	선택	페이지 번호
  size	Integer	선택	한 페이지에 표시할 포스팅 갯수

• Response
  대부분 JSON 형태로 반환된다.
  아래 예시의 반환 값은 페이지 번호, 사이즈, 전체페이지수, 전체 카운트 수, 그리고 포스팅에 대한 간략한 정보를 반환한다.

  {
  "page": 1,
  "size": 10,
  "totalPage": 150,
  "totalCount": 1496,
  "data": [
  	{
      "id": 1,
      "title": "제목1",
      "content": "내용1",
    },
    {
      "id": 2,
      "title": "제목2",
      "content": "내용2",
    },
    {
      "id": 3,
      "title": "제목3",
      "content": "내용3",
    }
  ]
  }

결론

결국 Client와 Server 간의 통신 계약이라고 보면 된다.
어떤걸 주면 너는 나에게 어떤 결과를 반환할지 적은 규칙이 API 명세서이고
이를 기반해서 서버를 개발한다.

앞으로 이 규약에 맞춰 머신러닝 API 명세를 하고 개발을 시작하려고 한다.
다만 보통 내 기억에 JSON으로 전달하거나 URL Params으로 전달하는데 이미지같은 경우에는 어떻게 하는지 정확하게 몰라 추가로 조사해볼 예정이다