IT STUDY LOG

[HTTP] 04. REST API 문서 작성 본문

devops bootcamp 4/개발 및 배포

[HTTP] 04. REST API 문서 작성

roheerumi 2023. 3. 23. 10:29

# 학습 목표

  • REST API에 대해 이해할 수 있다.
    • REST API 문서를 읽을 수 있다.
    • REST API에 맞춰 디자인할 수 있다.

 


# 학습 내용

1.  API 디자인의 선행 과정

  • API 디자인의 선행 과정: 관계형 데이터 모델링
    • 어떤 리소스를 요청/응답으로 주고 받을 것인가?
    • 해당 리소스에는 어떤 내용을 포함하는가?
    • ▶ 리소스(데이터)를 디자인하는 과정은 데이터 모델링의 한 부분으로 볼 수 있음
  • 관계형 데이터 모델
    • 정의
      • Codd 제안
      • 오늘날 대부분의 DBMS가 지원하는 데이터 모델
      • 데이터를 테이블(릴레이션) 형태로 저장
      • 관계를 기본키와 참조하는 외래키로 표현하는 데이터 모델
    • 릴레이션의 구조
  • HTTP API를 통한 데이터 전송
    • 직렬화(serialize)
      • 데이터가 HTTP 프로토콜을 통해 전달되기 위해 테이블(릴레이션)을 문자열로만 표현하는 것
      • 대표적인 방법으로 JSON 사용
      • [
          {
            "login_name": "kimcoding",
            "name": "김코딩",
            "email": "kimcoding@codestates.com",
            "is_admin": false
          },
          {
            "login_name": "devlee84",
            "name": "이개발",
            "email": "dev@codestates.com",
            "is_admin": false
          },
          {
            "login_name": "choiops",
            "name": "최운영",
            "email": "ops@codestates.com",
            "is_admin": true
          }
        ]
      • JSON의 자료형
        • 문자열
        • 숫자
        • 불린
        • 객체
        • null
  • 리소스에 따른 HTTP API
    • 이제 데이터 모델링을 통해 리소스 정의와 HTTP로 전송할 준비가 끝났다면, URI Path를 디자인
    • REST API는 리소스를 대표하는(representational) 문자열로 Path를 지정
    • # 사용자 목록 조회
      GET /users
      
      # 새 글 쓰기
      POST /article
      Content-Type: application/json
      
      { "title": "오늘의 TIL", "body": "오늘은 REST API를 배웠다", "author": "devlee84" }

 

2. API 디자인 실습 도구 안내

  • 스프레드시트 (Google Sheet)
    • 첫번째 행(row)에는 반드시 필드 이름이 들어가야 하며 공백을 포함하지 않는 영문자로 작성되어야 함 (_ 문자열은 사용 가능)
    • 두번째 행부터는 필드에 맞는 데이터가 들어가야 함
    • 필드에 데이터를 넣을 때는 모든 값이 일관된 자료형(type)이어야 함
  • 스프레드시트 기반 API 변환 도구 (Sheety) 
    • 개요
      • https://sheety.co/
      • 스프레드시트를 API로 변환시켜주는 도구
      • 일반적인 프로그래밍 언어별 API 작성 프레임워크
        • node.js : express, fastify
        • Python : Django, Flask
        • Java : Spring Boot
    • 사용 방법
      • New Project 버튼을 클릭한 후, From Google Sheet… 메뉴를 클릭
      • 화면에서의 안내와 같이 기존에 만들었던 시트의 URL을 입력하면, Sheetly와 연동이 가능(이미 작성되어있는 시트 이름이 자동으로 불러와짐)
      • Create Project 버튼을 클릭하면, 좌측에는 시트 목록이, 우측에는 어떻게 API 호출을 할 수 있는지를 확인 가능
    • API 활용 방법
      • API 호출에 필요한 정보를 확인 가능
      • 한 행(row)을 수정하려면 어떻게 호출해야 하는지를 보여 줌
      • 메소드: PUT
        • 수정(Update)을 위한 메소드
      • 엔드포인트: https://api.sheety.co/<사용자고유주소>/<프로젝트이름>
        • 일반적으로 도메인 이름 뒤에 나오는 주소는 Path에 속하지만, 이 경우 앞단의 고유 주소는 바뀌지 않으므로 프로젝트 이름까지 포함해 엔드포인트로 취급
      • Path: /user
        • 리소스 이름을 포함하고 있으며, 메소드와 Path가 RESTful하게 디자인
      • Path 파라미터: /<객체ID>
        • 객체 ID: 변수
      • 본문: JSON
          • 하나의 행을 생성하거나 수정하려면 본문이 반드시 있어야 함(message body)
          • Content-Type은 JSON으로 고정되어 있으며, 다음과 같은 형태를 함께 본문에 실어 요청을 보내야 함
        {
          "리소스이름": {
            "필드키A": "필드내용",
            "필드키B": "필드내용"
          }
        }
      • {
          "user": {
            "login_name": "kimcoding",
            "name": "김코딩",
            "is_admin": false
          }
        }

 

3.  API 문서 작성하기 (OpenAPI)

  • API 문서를 잘 작성해야 하는 이유
    • REST API를 사용하기 위해 필요한 정보
      • 요청 
        • 엔드포인트
        • Path
        • (필요하다면) Path 파라미터 또는 쿼리 파라미터
        • (필요하다면) 헤더 정보
        • 요청 본문 (POST나 PUT 등의 요청에 필요)
      • 응답
        • (요청을 보냈을 때 응답으로 오길 기대하는) 상태 코드
        • 응답 본문
    • API 문서의 예제
  • OpenAPI 명세서
    • Swagger
      • API 문서에 필요한 각종 항목의 내용을 정해진 규칙에 맞게 JSON이나 YAML 문서로 작성해놓으면 API 문서가 만들어지도록 하는 서비스
      • Swagger Editor :  YAML(데이터 포맷이자 마크업언어) 을 API 문서로 변환
      • 왼쪽 : YAML 파일 / 오른쪽 : 결과물
    • OpenAPI 명세

 

4. OpenAPI 명세 빠르게 알아보기

  • YAML 파일 작성 요령
    • 데이터는 key: value 의 형태
    • key: 와 value 사이에는 반드시 공백 필요
    • 계층 구조를 표현하기 위해서 2칸 혹은 4칸의 들여쓰기를 사용해야 함 (탭 문자열은 허용되지 않음)
  • 주요 key
    • openapi: OpenAPI의 명세 버전을 입력
    • info: API 문서 정보
      • description: API 문서 설명
      • version: API 의 버전을 명시
      • title: API 문서 제목
    • components: 데이터 모델과 관련한 내용
    • paths: URI Path와 관련한 내용
    • servers: URI 엔드포인트와 관련된 정보를 목록 형태로 입력
  • 데이터 모델 디자인 (components:)
  • components ─ schemas ─ <Model> ┬ type
                                   ├ required
                                   └ properties ─ <Field> ┬ type
                                                          └ example
    • <Model> : 모델 이름을 기입
    • <Field> : 필드 이름을 기입
    • type(자료형) : string(문자열), number(숫자), boolean(불린), array(배열), object(객체) 등
    • required 항목 : 필수적으로 데이터가 있어야 하는 필드 이름을 목록으로 작성
  • components:
      schemas:
        Article:  # 모델명
          type: object
          required:
            - 필드이름1
            - 필드이름2
          properties:
            필드이름1:
              type: 자료형
              example: '실제로 들어갈 데이터의 예시'
            필드이름2:
              type: 자료형
              example: '실제로 들어갈 데이터의 예시'
        Comment:  # 모델명
          type: object
          required:
            - 필드이름1
            - 필드이름2
          properties:
            필드이름1:
              type: 자료형
              example: '실제로 들어갈 데이터의 예시'
            필드이름2:
              type: 자료형
              example: '실제로 들어갈 데이터의 예시'
    • (예) 사용자(User) 모델을 YAML로 표현
  • components:
      schemas:
        User:  # 모델명
          type: object
          required:
            - login_name
            - name
          properties:
            login_name:
              type: string
              example: 'kimcoding'
            name:
              type: string
              example: '김코딩'
            is_admin:
              type: boolean
              example: true

 

  • URI Path 디자인 (paths:)
  • paths ─ /<Resource><Method> ┬ description
                                   ├ parameters
                                   └ responses ─ <StatusCode> ┬ description
                                                              └ content ─ <ContentType> - schema - <DataModel>
      • <Resource> : Path 그 자체를 입력 (/ 문자열로 시작)
      • <Method> : HTTP 메소드를 입력 (get, post, put, delete 등)
      • <StatusCode> : 응답 코드를 입력하고 따옴표로 묶어주여야 함
      • <ContentType> : MIME 타입을 입력 (default: application/json)
      • <DataModel> 은 앞서 언급한 데이터 모델 포맷을 넣을 수 있음(직접 넣거나, $ref 지시자를 이용해 참조로 넣을 수 있음)
  • paths:
      /패스1:  # url path
        get:
          description: '해당 엔드포인트에 대한 설명'
          parameters:
            - in: path
              name: 파라미터명
              description: '패스 파라미터에 대한 설명'
              schema:
                type: 자료형
              required: 필수여부
          responses:
            '응답코드':
              description: '응답 코드에 대한 설명'
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/모델이름'
        post:
          description: '해당 엔드포인트에 대한 설명'
          requestBody:
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/모델이름'
          responses:
            '응답코드':
              description: '응답 코드에 대한 설명'
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/모델이름'
  • (예) “블로그 글 전체 조회” 일 경우 URL Path 디자인 (데이터 모델에 Article이 이미 정의되어 있다고 가정)
    • 요청 : GET /article 
    • 응답 : 200과 아래와 같은 JSON
    • {
        "article": [
          {
            "title": "3월 15일의 TIL",
            "body": "오늘은 REST API를 배웠다",
            "id": 2
          },
          {
            "title": "3월 16일의 TIL",
            "body": "REST API를 복습했다",
            "id": 3
          }
        ]
      }

 

 

'devops bootcamp 4 > 개발 및 배포' 카테고리의 다른 글

[HTTP] 07. Google Spreadsheat & Sheety & Swagger 실습  (0) 2023.03.23
[HTTP] 05. HTTPS  (0) 2023.03.23
[HTTP] 03. 잘 설계된 HTTP API (REST API)  (0) 2023.03.22
[HTTP] 02. HTTP 헤더  (0) 2023.03.22
[HTTP] 01. Cookie  (0) 2023.03.22
Comments