API 문서화는 왜 해야 할까?

• API 문서화는 왜 해야 할까?
• API 문서에는 어떤 내용들을 포함해야 할까?
  • 참조 문서
  • 데이터 모델
  • 목표 문서화하기
  • 보안 문서화하기
  • API의 개요 제공하기
• 사용자 안내서
• 구현 세부사항
• 문서의 개정과 폐기

API 문서화는 왜 해야 할까?

API 디자이너는 API 프로젝트의 다양한 측면에 참여해야 하는데, 이 중에 가장 중요한 것 중 하나가 바로 문서화입니다. 뛰어나거나 단순하거나 모든 API에는 문서화가 필수입니다. 예를 들어 일상생활에서도 알람시계 샀을 때 어떻게 알람을 설정하는지, + - 버튼을 누른다면 어떤 일이 벌어지는지 정보를 제공해 주는 사용자 매뉴얼이 함께 들어있습니다. 이것도 문서화의 일부로 볼 수 있습니다. 그리고 알람 시계를 만들어야 하는 개발자는 디자이너에게 해당 동작을 설명하는 구현 명세를 받았을 것입니다.

구현 명세가 없다면 디자이너가 의도한 대로 디자인을 구현할 가능성은 거의 없습니다. API 디자이너는 디자인하려는 API에 대한 해당 문서를 작성하거나 최소한 기여라도 해야 합니다.

가장 잘 알려진 API 문서는 API의 인터페이스 컨트렉트를 설명하는 참조 문서입니다. 이 참조 문서는 사용 가능한 목표를 나열하고 입력 및 출력을 설명합니다.

API 문서는 다양한 유즈케이스와 이를 달성하는 방법을 설명하는 운영 메뉴얼이 제공되어야 합니다.

또한, 모든 소프트웨어와 마찬가지로 API를 수정할 때, 브레이킹 체인지가 없는 경우라도 추가되거나 변경된 기능에 대해서 변경 이력으로 알려주는 것이 좋습니다. 디자이너는 변경 내용을 알고 있으므로 디자이너가 변경사항을 열거해야 합니다. 그리고 API에 대한 설명을 제공하는 것만으로는 누군가 API를 구현하기에는 충분하지 않을 수 있기 때문에 API 문서화를 해야 합니다.

API 문서에는 어떤 내용들을 포함해야 할까?

참조 문서

참조 문서는 API의 인터페이스 컨트랙트를 설명하는 문서로, 사용 가능한 목표를 나열하고 입력 및 출력을 설명합니다. openAPI 명세 같은 API 명세 포맷은 여러분이 API 참조 문서를 작성할 때 도움이 되어줄 것입니다. 중요한 점은 도구가 아니라 참조 문서가 어떤 정보들을 API 명세 포맷과 그것을 화면으로 표현해 주는 렌더링 도구에 제공해 주어야 하는가입니다. 데이터 모델과 목표, 보안을 문서화하고, 마지막으로 API 자체에 대한 유용한 정보를 추가하는 방법을 설명드리겠습니다.

데이터 모델

components:
  schemas:
    reservationStatus:
      type: string
      description: 예약 상태
      enum:
        - RESERVED
        - CANCELED
        - RETROSPECTIVE_WAITING
        - RETROSPECTIVE_COMPLETE
    date:
      type: string
      format: date <-- 날짜 속성은 날짜 형식(YYYY-MM-DD)을 사용하는 문자열입니다.
      desciption: 예약 일자

reservationStatus 속성에는 가능한 값들로 (“RESERVED”, “CANCELED”, “RETROSPECTIVE_WAITING”, “RETROSPECTIVE_COMPLETE”)로 enum 목록에 정의되어 있습니다.

date 속성은 date 포맷을 이용합니다. YYYY-MM-DD를 쓰는 ISO 8601 포맷의 사용을 의미합니다.

API의 데이터 모델에 대한 기본이지만 가치 있는 참조 문서는 API 설계 중에 수행된 작업을 재사용하여 작성할 수 있습니다. 속성, 유형 및 필수 사항이 있는 경우 예제 또는 광범위한 설명을 제공하지 않고 간단한 데이터 모델에 충분할 수 있습니다.

목표 문서화하기

목표의 참조 문서는 목표의 목적, 사용에 필요한 것, 성공 또는 실패 시 컨슈머가 얻는 피드백의 종류 및 대상 그룹의 일부인 경우를 설명합니다.

paths:
  /admin/reservations: //리소스 경로
    get: //리소스에서 쓰이는 HTTP 메서드
      description: 모든 예약 목록을 조회합니다 //요약된 설명
      parameters:
        - name: page
          in: query
          description: 페이지 번호(기본값 = 1)
          required: false
        - name: size
          in: query
          description: 포함될 요소의 개수(기본값 = 10)
          required: false
      responses: //목표에서 가능한 출력들
        "200":
          description: 성공적으로 예약 목록을 조회했습니다
          content:
            application/json:
              schema:
                type: object
                [...]
          pagination:
                    $ref: "#/components/schemas/pagination" //피드백 데이터 모델의 참조
        "403":
          description: 조회할 권한이 없습니다 // 피드백에 대한 간략한 설명
[...]

목표는 요약과 가능한 모든 리스폰스, 데이터 모델 목록을 통해 자세한 내용을 생략할 수 있습니다.

보안 문서화하기

참조 문서에는 반드시 보안과 관련된 정보도 포함되어야합니다.

예를 들어 코드숨 공부방 예약하기 API가 OAuth 2.0을 사용하고 인증 섹션에 reservation:delete 또는 reservation:admin 스코프를 지니고 있어야 예약 삭제 목표를 사용할 권한이 있을 때에 다음과 같이 묘사할 수 있습니다.

components:
  securitySchemes:   <---- 보안과 스코프 정의
  ReservationsAPIScopes:
    type: oauth2
    flow:
      implicit:
        authorizationUrl: "https://auth.codesoom.com/authorize"
        scopes:
          "reservation:delete": Delete reservations
          "reservation:read": List reservations
          [...]
[...]
paths:
  /reservations:
    delete:
      summary: 예약 삭제
      security: <---- 목표를 사용하기 위해서는 스코프가 필요함
        - ReservationAPIScopes:
          - "reservation:delete"
          - "reservation:admin"
[...]

API를 디자인할 때 보안을 정의했으므로, 어떠한 보안이 적용이 되었는지, 사용 가능한 스코프는 무엇인지, 각 목표를 사용하는데 필요한 스코프는 무엇인지를 설명하는 기본 참조 문서를 제공하는 것은 생각보다 많은 노력이 필요하지 않습니다.

API의 개요 제공하기

마지막으로 API 레벨의 참조 문서가 있습니다.

Rservations API(1.1.0) The Codesoom Rservations API team : codesoom@gmail.com | URL : www.codesoom.com

info:
  title: 관리자 API
  version: "1.0.0"
  description: |
  contact:
    name: The Codesoom Rservations API team
    email: codesoom@gmail.com 
    url: www.codesoom.com

해당 API 정보는 openAPI 명세 파일의 info절을 사용한 것을 알 수 있습니다. API 참조 문서에는 API에 대한 간략한 설명은 필수로 들어가야 합니다. 이러한 설명은 이름만으로는 충분히 이해가 되지 않을 때 컨슈머가 API로 무엇을 할 수 있는지 알 수 있게 도와줍니다. 연락처 정보는 선택 사항이지만, 사용자가 더 많은 정보나 도움이 필요한 경우를 생각해 늘 제공하는 게 좋습니다.

사용자 안내서

API 스펙 문서만 봐서는 이 API를 어떻게 사용하는지 전부 알 수는 없습니다. 그래서 사용자가 API를 사용하는 방법을 알 수 있도록, 사용자 안내서를 작성하여야 합니다.

사용자 안내서는 사용자가 이 API를 사용하여 할 수 있는 예제로 유즈 케이스를 기술하면 됩니다. 예를 들어 아주 단순하게 글로 작성할 수도 있고, 혹은 도표 같은 것을 사용하여 흐름도를 보여줄 수도 있습니다. 아니면 다른 API들을 조합해서 사용하여 특정한 일을 할 수 있는 일을 기술할 수도 있을 것입니다.

뿐만 아니라 실제로 API를 호출하기까지 컨슈머가 무슨 일을 해야 하는지도 알려주어야 합니다. 만약 API 호출 시 보안 토큰이 필요하다면 토큰을 어떻게 획득하는지, 획득한 토큰을 어디서 사용할 수 있는지에 대한 내용이 사용자 안내서에 포함되어야 합니다.

사용자 안내서는 모든 API의 일반적인 동작과 원칙을 제공함으로써 컨슈머가 API를 보다 잘 쓸 수 있게 도와주어야 합니다. 문서화는 어떻게 에러가 처리되는지, 가능한 데이터 포맷은 무엇인지, 어떤 언어를 지원하는지, 페이지 처리는 어떻게 하는지와 같은지 등을 다룰 수 있겠죠.

하지만 문서로만 이루어진 정적 문서화가 유일한 선택지는 아닙니다. 현재 많이 사용하고 있는 API 참조 문서 중에 사용자 안내서를 포함해서 실제 컨슈머가 API를 리퀘스트를 했을 때 응답 값을 볼 수 있습니다. 다른 곳에서는 개발자 포털 내부에서도 유즈케이스를 단계 별로도 테스트해 볼 수 있도록 제공해 줍니다.

구현 세부사항

사용자에게 편리한 사용자 안내서를 제공했다면, API를 사용해서 실제로 구현하는 담당자에게는 구현 세부사항에 대한 정보를 제공해야 합니다. 왜냐하면 API를 실제로 구현하는 데에는 데이터 매핑, 오류 매핑, 보안 데이터 및 제어, 내부 비즈니스 / 기술 규칙에 따른 예상 동작에 대한 정보가 필요하기 때문이죠.

예를 들어 코드숨 공부방 예약 내역은 매일 11시에 초기화가 됩니다. 그래서 11시에서 12시 사이에는 예약을 하지 못하도록 막아야 합니다. 만약 이를 구현 담당자가 몰라서 해당 시간에 예약을 막지 못했다면 예약을 초기화하는 중에 사용자가 예약을 하는 문제가 발생할 수도 있습니다. 이러한 문제를 예방하기 위해 상세 구현 내용을 API 문서에 포함하여, 구현하는 담당자에게 이러한 정보를 제공할 수 있습니다.

문서의 개정과 폐기

API 디자인과 브레이킹 체인지 등 많은 것들이 변화가 있을 때, 우리는 사용자들에게 알려 줘야 합니다.

예를 들어 API에서 더 이상 지원하지 않을 예정인 속성에 deprecated를 추가하여, 최신 API를 사용하도록 사용자에게 알려줄 수 있습니다. 이렇게 문서에 작성해서 제공할 수도 있고 혹은 다음과 같이 응답 데이터에 메타 데이터를 동적으로 추가하여 제공할 수도 있습니다.

200 OK
Sunset: Mon, 3, Feb 2022 23:59:59 GMT

위의 응답은 기존에 사용했던 리소스를 2022년 2월 3일까지만 이용 가능하다는 것을 나타냅니다.

그리고 변경 이력을 통해 API 디자인이 어떻게 변화해 왔는지 알려줘야 합니다. 그래야 새로운 API 버전으로 올바르게 업그레이드할 수 있을 것입니다.