IT STUDY LOG
[HTTP] 04. REST API 문서 작성 본문
# 학습 목표
- 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
- 직렬화(serialize)
- 리소스에 따른 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 문서의 예제
- REST API를 사용하기 위해 필요한 정보
- OpenAPI 명세서
- Swagger
- API 문서에 필요한 각종 항목의 내용을 정해진 규칙에 맞게 JSON이나 YAML 문서로 작성해놓으면 API 문서가 만들어지도록 하는 서비스
- Swagger Editor : YAML(데이터 포맷이자 마크업언어) 을 API 문서로 변환
- 왼쪽 : YAML 파일 / 오른쪽 : 결과물
- OpenAPI 명세
- API 문서를 작성하는 YAML 파일 규칙
- API 문서 살펴보기
- Swagger
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 |