DevOps Day 13 (3.23) HTTP_API 문서 작성

API 디자인의 선행 과정

REST API는 데이터나 자원(resource)을 HTTP URI로 표현하는 데에 그 목적이 있습니다. 따라서 API 작성에 생각할 포인트들이 있습니다.
- 어떤 리소스를 요청/응답으로 주고 받을 것인가?
- 해당 리소스에는 어떤 내용을 포함하는가?

전달 과정에 필요한 데이터를 디자인 하는 이러한 과정은 큰 틀에서 데이터 모델링의 한 부분으로 볼 수 있습니다. 우리의 데이터는 여러 개의 표(table) 형식으로 정의할 것이므로 관계형 데이터 모델링이라고 할 수 있습니다.

 

블로그에 필요한 데이터 모델은?

- 사용자
- 블로그 글
- 댓글
데이터 모델은 앞서 언급한 바와 같이 표 형식으로 표현합니다. 사용자의 예시 :

- 열 (column) 먼저 정의되어 있어야 형 (row) 진행 할 수 있음

- 필드를 정의하고 나서, 데이터를 넣을 때는 모든 값이 일관된 자료형(type)이어야 합니다.
- 만일 필드 정보(스키마라고 합니다)만 표시하고자 할 때에는 반드시 자료형을 같이 적어주는 것이 필요합니다.

 

HTTP API를 통한 데이터 전송
데이터가 어떠한 정해진 문자열 형태로 변환되는 과정을 직렬화(serialize)라고 합니다. JSON 형태의 포멧을 사용하여 HTTP의 Content-type으로도 사용이 가능합니다. 상단 표를 Script 방식으로 표현하였습니다.

JSON에서 허용하는 자료형은 : 문자열, 숫자, 불린, 객체, null 입니다.

 

리소스에 따른 HTTP API
데이터 모델링을 통해 리소스 정의와 HTTP로 전송할 준비가 끝났다면, URI Path를 디자인합니다.

API 디자인 실습 도구 안내

스프레드시트 (Google Sheet)
관계형 데이터 모델링을 시작하기에 좋은 도구는 바로 스프레드시트를 사용하는 것입니다.
시트 사용시 반드시 지켜야 할 규칙들이 있습니다 :
- 첫번째 행(row)에는 반드시 필드 이름이 들어가야 합니다. 공백을 포함하지 않는 영문자로 작성되어야 합니다. _ 문자열은 사용할 수 있습니다.

- 두번째 행부터는 필드에 맞는 데이터가 들어가야 합니다.

- 필드에 데이터를 넣을 때는 모든 값이 일관된 자료형(type)이어야 합니다.

 

스프레드시트 기반 API 변환 도구 (Sheety)
일반적으로 node.js 생태계에서는 express, fastify, Python에서는 Django, Flask, Java에서는 Spring Boot라는 프레임워크를 이용해서 API 서버를 제작합니다. Sheety https://sheety.co/ 는 스프레드시트를 API로 변환시켜주는 도구입니다.

 

API 활용 방법

1. 메소드: PUT
수정(Update)을 위한 메소드입니다. 여기서는 PATCH 대신 PUT을 채택했습니다.

 

2. 엔드포인트: https://api.sheety.co/<사용자고유주소>/<프로젝트이름>
일반적으로 도메인 이름 뒤에 나오는 주소는 Path에 속하지만, 이 경우 앞단의 고유 주소는 바뀌지 않으므로 프로젝트 이름까지 포함해 엔드포인트로 취급합니다.

 

3. Path: /user
리소스 이름을 포함하고 있으며, 메소드와 Path가 RESTful하게 디자인되어 있습니다.

 

4. Path 파라미터: /<객체ID>
객체 ID는 변수입니다. 특정 행(row)을 수정하려는 것이 이 API의 목적이므로, 해당 행을 선택해서 URI에 넘겨주어야 합니다. 각 고유의 행은 객체 ID를 가지고 있습니다. (GET 요청으로 확인할 수 있습니다) 이 객체 ID로 특정 행을 선택해 해당 행의 내용을 수정할 수 있습니다.

 

5.본문: JSON
하나의 행을 생성하거나 수정하려면 본문이 반드시 있어야 합니다.
https://sheety.co/

 

API 문서 작성하기 (OpenAPI)
OpenAPI 명세서
API 문서에 필요한 각종 항목의 내용을 정해진 규칙에 맞게 JSON이나 YAML 문서로 작성해놓으면, 멋진 API 문서가 만들어지도록 만든 서비스가 존재합니다. 바로 Swagger라는 서비스입니다. 특히 그 중에서도 Swagger Editor를 사용하면 YAML을 API 문서로 변환해줍니다.
https://editor.swagger.io/?_ga=2.216479696.775499509.1678951575-1854599934.1678857571

 

OpenAPI 명세 빠르게 알아보기
YAML 파일 작성 요령을 간단하게 설명합니다.
- 데이터는 key: value 의 형태
- key: 와 value 사이에는 반드시 공백 필요
- 계층 구조를 표현하기 위해서 2칸 혹은 4칸의 들여쓰기를 사용해야 함 (탭 문자열은 허용되지 않음)

 

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

 

데이터 모델 디자인 (Componets)
- <Model>에는 모델 이름을 기입합니다.
- <Field>에는 필드 이름을 기입합니다.
- type(자료형)에는 string(문자열), number(숫자), boolean(불린), array(배열), object(객체)가 포함될 수 있습니다.
- required 항목에는 필수적으로 데이터가 있어야 하는 필드 이름을 목록으로 넣습니다.

 

URI Path 디자인 (Paths)
- <Resource>에는 Path 그 자체를 입력합니다. / 문자열로 시작합니다.
- <Method>에는 HTTP 메소드를 입력합니다. get, post, put, delete 등이 될 수 있습니다.
- <StatusCode>에는 응답 코드를 입력합니다. 이 때 '200' 과 같이 따옴표로 묶어서 써줘야 합니다.
- <ContentType>에는 MIME 타입을 입력합니다. application/json 이 보통입니다.
- <DataModel> 은 앞서 언급한 데이터 모델 포맷을 넣을 수 있습니다.
   - 직접 넣거나
   - 또는 $ref 지시자를 이용해 참조로 넣을 수 있습니다.

 

HTTPS (hyper Text Transfer Protocol Secure Socket Layer)
HTTPS는 HTTP 요청을 SSL 혹은 TLS라는 알고리즘을 이용해, HTTP 통신을 하는 과정에서 내용을 암호화하여 데이터를 전송하는 방법입니다. 클라이언트 <-> 서버와 암호화

인증서
HTTPS 프로토콜의 또 다른 특징 중 하나는 브라우저가 응답과 함께 전달된 인증서 정보를 확인할 수 있다는 점입니다. 브라우저는 인증서의 도메인과 데이터를 제공한 제공자의 도메인을 비교할 수 있기 때문에 인증서의 도메인 정보와 데이터 제공자의 도메인 정보가 다른 '중간자 공격'을 감지하여 보안 위협으로부터 사용자 및 사용자의 데이터를 보호할 수 있습니다.

 

인증서 (certificate)
- 데이터 제공자 신원 보상
- 도메인 종속

CA (Certificate Authority)

- 공인 인증서 발급 기관