[23. March] REST API / TIL #1

• REST API
  - 데이터나 자원을 HTTP URI로 표현하는 데에 목적이 있다.
  - API 작성을 위해서는 어떠한 리소스를 요청/응답으로 주고 받을 것인지, 해당 리소스에 어떤 내용을 포함하는지 보아야한다.
  - 리소스 : 데이터 모델링의 한 부분으로 데이터를 여러 개의 표 형식으로 정의할 수 있다. 이것을 관계형 데이터 모델링 이라고 한다.
• 관계형 데이터베이스
  - 행과 열(필드)로 구성된 표 형식으로 표현된다.
  - 데이터를 넣을 때는 모든 값이 일관된 자료형이어야 한다.
  - 필드 정보(스키마)만 포함하고 싶을 때는 자료형을 반드시 같이 적어주어야 한다.
• HTTP API
  - 데이터베이스 같은 데이터가 HTTP 프로토콜을 통해 전달되려면, HTTP body는 문자열로만 이루어져 있기 때문에 표를 문자열로만 표현해야 한다. 이러한 과정을 '직렬화(serialize)'라고 한다.
  - JSON 형태의 포맷을 사용하는 것이 직렬화의 대표적인 방법으로 HTTP의 Content-Type으로 사용이 가능하다.
  - JSON에서 허용하는 자료형 : 문자열, 숫자, 불린(boolean), 객체, null

login_name	name	email	is_admin
kimcoding	김코딩	kimcoding@codestates.com	false
noeyaes	오시연	ocean1220@naver.com	true
devlee94	최개발	dev@codestates.com	false

• 위 데이터베이스 표를 직렬화한 형태는 다음과 같다.

[
  {
    "login_name": "kimcoding",
    "name": "김코딩",
    "email": "kimcoding@codestates.com",
    "is_admin": false
  },
  {
    "login_name": "noeyaes",
    "name": "오시연",
    "email": "ocean1220@naver.com",
    "is_admin": true
  },
  {
    "login_name": "devlee84",
    "name": "최개발",
    "email": "dev@codestates.com",
    "is_admin": false
  }
]

 

• 데이터 모델링을 통해 리소스 정의와 HTTP 전송 준비가 끝났다면, URI Path를 디자인 한다.
• 잘 설계된 HTTP API(REST API)는 리소스를 대표하는 문자열로 Path를 지정한다.

// #URI Path 디자인#

GET /users
// 사용자의 목록을 받아온다.

POST /article
Content-Type : application/json
{ "title": "오늘의 TIL", "body": "오늘은 REST API를 배웠다.", "author": "ocean1220" }
// 새 글 쓰기

---

API 문서 작성하기

• Swagger Editor : API 문서에 필요한 각종 항목의 내용을 규칙에 맞게 JSON 이나 YAML 문서로 작성해 놓으면, API 문서로 변환 되도록 만든 서비스
• REST API를 사용하기 위해 필요한 정보
  - 엔드 포인트
  - Path
  - 요청 본문(body) / POST나 PUT 등의 요청에 필요)
  - (필수 x) Path 파라미터 또는 쿼리 파라미터
  - (필수 x) 헤더 정보
• 응답 정보
  - 상태 코드
  - 응답 본문(body)
• 관계형 데이터 모델링을 하기 위해서 스프레드 시트(Google Shee)를 사용하는 것이 좋다.
• 시트 사용 시 반드시 지켜야 할 규칙
  1. 첫 번째 행에는 반드시 공백을 포함하지 않는 영문자 필드 이름이 들어간다. (문자열 사용 가능)
  2. 두 번째 행부터는 필드에 맞는 데이터가 들어간다.
  3. 필드에 데이터를 넣을 때는 모든 값이 일관된 자료형이어야 한다.

 

OpenAPI 명세

• 데이터는 key: value의 형태 / 'key:'와 'value' 사이에는 반드시 공백 필요
• 계층 구조를 표현하기 위해 2칸 혹은 4칸의 들여쓰기를 사용해야 함 (탭 문자열 허용 x)
• 주요 key

key	info
openapi	OpenAPI의 명세 버전을 입력한다. (3.0.0 or 3.0.1)
info	API 문서 정보. 하위 계층이 존재하며, 하위 계층에서 사용할 수 있는 키는 다음과 같다. - description : 문서 설명 - version : 버전 명시 - title : 문서 제목
components	데이터 모델과 관련된 내용 (다음에 설명하는 내용 참고)
paths	URI Path와 관련된 내용 (다음에 설명하는 내용 참고)
servers	URI 엔드 포인트와 관련된 정보, 목록 형태의 값을 입력한다.

---

데이터 모델 디자인 ( components: )

// 계층 구조
components ─ schemas ─ <Model> ┬ type
                               ├ required
                               └ properties ─ <Field> ┬ type
                                                      └ example
                                                      
// <Model> : 모델 이름 기입
// <Field> : 필드 이름 기입
// type : strinf, number, boolean, array, object 기입
// required : 필수적으로 데이터가 있어야 하는 필드 이름을 목록으로 기입

---

// 실제 디자인 형태
components:
  schemas:
    User:  // 여기에 모델명을 넣습니다. 
      type: object
      required:
        - login_name
        - name
      properties:
        login_name:
          type: string
          example: 'noeyaes'
        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> : 응답 코드 입력 / '200' 과 같이 따옴표로 묶어서 작성
 // <ContentType> : MIME 타입을 입력. application/json 이 보통
 // <DataModel> : 데이터 모델 포맷을 직접 넣거나, $ref 지시자를 이용해 참조를 넣는다.

---

paths:
  /article:
    get:
      description: '블로그 글 전체 조회'
      responses:
        '200':
          description: '성공 응답'
          content:
            application/json:
              schema:
                type: object
                properties:
                  article:
                    type: array
                    items:
                      $ref: '#/components/schemas/Article'