학습 목표
- 쿠키의 작동 원리를 이해할 수 있다
- HTTP 헤더의 역할에 대해 이해할 수 있다.
- 표현, 콘텐츠 협상 등 다양한 헤더의 역할에 대해 알 수 있다.
- REST API에 대해 이해할 수 있다.
- REST API 문서를 읽을 수 있다.
- REST API에 맞춰 디자인할 수 있다.
- HTTPS의 개념을 이해할 수 있다.
- HTTP와 HTTPS의 차이점을 이해할 수 있다.
API 디자인의 선행 과정
- 관계형 데이터 모델링
- REST API는 데이터나 자원을 HTTP URI로 표현하는 것이 목표
- 어떤 리소스를 요청/응답으로 주고 받을 것인가?
- 해당 리소스에는 어떤 내용을 포함하는가?
- 전달 과정에 필요한 데이터를 디자인 하는 이러한 과정은 큰 틀에서 데이터 모델링의 한 부분으로 볼 수 있음
- 여러 개의 표 형식으로 정의할 것이므로 관계형 데이터 모델링이라고 할 수 있음
- REST API는 데이터나 자원을 HTTP URI로 표현하는 것이 목표
- 블로그에 필요한 데이터 모델은?
- 사용자
- 예시
login_name name email is_admin kimcoding 김코딩 kimcoding@codestates.com false devlee 이개발 dev@codestates.com false choiops 최운영 ops@codestates.com true - 블로그 글
- 댓글
- 데이터가 행(row)의 형태로 쌓옂기 전에 필드(열, column)이 먼저 정의되어야 함
- 필드 정의 후 데이터를 넣을 때는 모든 값이 일관된 자료형(type)이어야 함
- 따라서, 필드 정보(스키마)만 표시하고자 할 때에는 반드시 자료형을 같이 적어주어야 함
필드 이름 타입(자료형) login_name 문자열 name 문자열 email 문자열 is_admin 불린(boolean)
- 사용자
- HTTP API를 통한 데이터 전송
- 위와 같은 데이터가 HTTP 프로토콜을 통해 전달되려면, 표를 문자열로만 표현해야 함
- 이와 같이, 데이터가 어떠한 정해진 문자열 형태로 변환되는 과정을 직렬화(serialize)라고 함
- 위의 표를 직렬화하는 대표적인 방법으로, 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에서 허용하는 자료형은 다음과 같으며, 자료형은 암묵적으로 정의되어 있음
- 문자열
- 숫자
- 불린(boolean)
- 객채
- null
- 위와 같은 데이터가 HTTP 프로토콜을 통해 전달되려면, 표를 문자열로만 표현해야 함
- 리소스에 따른 HTTP API
- 데이터 모델링을 통해 리소스 정의와 HTTP로 전송할 준비가 끝났다면, URI Path 디자인
- REST API는 리소스를 대표하는(repersentational) 문자열로 Path를 지정함
- POST /article Content-Type: application/json { "title": "오늘의 TIL", "body": "오늘은 REST API를 배웠다", "author": "devlee84" }
API 디자인 실습 도구 안내
- 실제로 애플리케이션을 개발할 때에는 데이터베이스와 데이터베이스 접근 코드를 사용
- 스프레드시트는 API 연습 도구로 사용
- 스프레드시트 (Google Sheet)
- 어떤 형태로 데이터가 저장되어 있는지, 필드는 어떤 것들이 있는지 쉽게 알아볼 수 있어서 유용함
- 첫번째 행(row)에는 반드시 필드 이름이 들어가야 하며, 공백을 포함하지 않는 영문자로 작성되어야 함
- 두번째 행부터는 필드에 맞는 데이터가 들어가야 함
- 필드에 데이터르 ㄹ넣을 때는 모든 값이 일관된 자료형(type)이어야 함
- 스프레드시트 기반 API 변환 도구 (Sheety)
- HTTP 호출로 구글 시트의 내용을 조회하거나 새로운 열을 생성하는 등의 작업 가능
API 문서 작성하기 (Open API)
- API 문서를 잘 작성해야 하는 이유
- REST API를 사용하기 위해 필요한 정도
- 엔드포인트
- Path
- Path 파라미터 또는 쿼리 파라미터
- 헤더 정보
- 요청 본문
- API 문서에 응답 정보도 같이 적혀있다면, 굳이 요청을 보내지 않아도 응답이 어떤 형태인지 알 수 있음
- 상태코드
- 응답 본문
- REST API를 사용하기 위해 필요한 정도
- OpenAPI 명세
- 데이터는 key: value의 형태이며, key: 와 value 사이에는 반드시 공백 필요
- 계층 구조를 표현하기 위해서 2칸 혹은 4칸의 들여쓰기를 사용해야 하며, 탭 문자열은 허용되지 않음
- 주요 key
- openapi: OpenAPI의 명세 버전 입력
- info: API 문서 정보, 하위 계층이 존재하며 하위 계층에서 사용할 수 있는 키는 다음과 같음
- description: API 문서 설명
- version: API의 버전 명시
- title: API 문서 제목
- components: 데이터 모델과 관련한 내용
- <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: '이 필드에 실제로 들어갈 데이터의 예시를 적습니다'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 - components ─ schemas ─ <Model> ┬ type ├ required └ properties ─ <Field> ┬ type └ example
- paths: URI Path와 관련한 내용
- <Resource> Path 자체 입력, / 문자열로 시작
- <Method> HTTP 메소드 입력, get, post, put, delete 등
- <StatusCode> 응답 코드 입력, ‘200’ 처럼 따옴표로 묶어서 써줘야 함
- <ContentType> MIME 타입 입력
- <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/모델이름'
servers: URI 엔드포인트와 관련된 정보로, 목록 형태의 값을 입력
앞으로 개발하려면 꼭 알아야할.. API 작성 요령
처음 보는 거라서 너무 어려웠다
앞으로 반복해서 보다보면 익숙해지겠지?
'Code States > TIL' 카테고리의 다른 글
| [0324] WAS와 Web Server - 서버 (0) | 2023.03.24 |
|---|---|
| [0323] HTTP - HTTPS (0) | 2023.03.23 |
| [0323] (페어) HTTP - REST API 문서 작성 (0) | 2023.03.23 |
| [0322] HTTP - 잘 설계된 HTTP API (REST API) (0) | 2023.03.22 |
| [0322] HTTP - HTTP 헤더 (0) | 2023.03.22 |