API 디자인의 선행 과정
API 디자인의 선행 과정: 관계형 데이터 모델링
- 어떤 리소스를 요청/응답으로 주고 받을 것인가?
- 해당 리소스에는 어떤 내용을 포함하는가?
전달 과정에서 필요한 데이터를 디자인 하는 이러한 과정은 큰 틀에서 데이터 모델링의 한 부분으로 볼 수 있다. 우리는 데이터의 여러 개의 표 형식으로 정의할 것이므로 관계형 데이터 모델링이라고 할 수 있다.
HTTP API를 통한 데이터 전송
-
표를 전달하려면 문자열로만 표현해야 함
-
JSON 형태의 포맷을 사용하는 것이 일반적, HTTP의 Content-Type으로도 사용 가능
-
JSON 자료형이 암묵적으로 정의되어 있음
- 문자열
- 숫자
- 불린(boolean)
- 객체
- null
리소스에 따른 HTTP API
- 리소스 정의와 HTTP로 전송할 준비가 되었다면 URI Path를 디자인 함
API 디자인 실습 도구 안내
스프레드시트
- 어떤 형태로 데이터가 저장되어 있는지, 필드는 어떤 것들이 있는지 쉽게 알아볼 수 있어 유용함.
- 첫번째 행(row)에는 반드시 필드 이름이 들어가야 함. 공백을 포함하지 않은 영문자로 작성되어야 함. 문자열은 사용할 수 있음.
- 두번째 행부터는 필드에 맞는 데이터가 들어가야 함.
- 필드에 데이터를 넣을 때는 모든 값이 일관된 자료형이어야 함.
API 활용 방법(스프레드시트 기반 API 변환 도구 (Sheety) 사용)
한 행을 수정하려면 어떻게 호출해야 하는가?
- 메소드: PUT
수정(Update)을 위한 메소드입니다. 여기서는 PATCH 대신 PUT을 채택 - 엔드포인트: https://api.sheety.co/<사용자고유주소>/<프로젝트이름>
일반적으로 도메인 이름 뒤에 나오는 주소는 Path에 속하지만, 이 경우 앞단의 고유 주소는 바뀌지 않으므로 프로젝트 이름까지 포함해 엔드포인트로 취급 - Path: /user
리소스 이름을 포함하고 있으며, 메소드와 Path가 RESTful하게 디자인되어 있음 - Path 파라미터: /<객체ID>
객체 ID는 변수입니다. 특정 행(row)을 수정하려는 것이 이 API의 목적이므로, 해당 행을 선택해서 URI에 넘겨주어야 함. 각 고유의 행은 객체 ID를 가지고 있음. (GET 요청으로 확인) 이 객체 ID로 특정 행을 선택해 해당 행의 내용을 수정할 수 있음. - 본문: JSON
하나의 행을 생성하거나 수정하려면 본문이 반드시 있어야 합니다. Content-Type은 JSON으로 고정되어 있으며, 다음과 같은 형태를 함께 본문에 실어 요청을 보내야 합니다.
주의
- 실제로 애플리케이션을 개발할 때, 스프레드시트를 주 저장소로 사용하는 일은 매우 드뭅니다. 스프레드시트를 API 연습 도구로 사용하는 것은 학습에 용이하기 때문입니다.
- 실제 애플리케이션에서 사용하는 주 저장소는 바로 데이터베이스입니다. 따라서, 시트 대신 데이터베이스를 사용하고, sheety 서비스 대신 프로그래밍 언어를 통해 작성한 데이터베이스 접근 코드가 API 서버의 역할을 대신합니다.
- 데이터베이스와 프로그래밍 언어를 활용해 API 서버를 작성하는 것은 백엔드의 기본 중의 기본입니다.
API 문서 작성하기 (OpenAPI)
API 문서를 잘 작성해야 하는 이유
- 요청에 필요한 정보
- 엔드포인트
- Path
- (필요하다면) Path 파라미터 또는 쿼리 파라미터
- (필요하다면) 헤더 정보
- 요청 본문 (POST나 PUT 등의 요청에 필요)
- 응답 정보
- (요청을 보냈을 때 응답으로 오길 기대하는) 상태 코드
- 응답 본문
OpenAPI 명세서 (Swagger)
정해진 규칙에 맞게 JSON이나 YAML문서로 작성해 놓으면 API문서가 만들어지도록 하는 서비스 존재
Swagger Editor를 사용하면 YAML을 API 문서로 변환해줌
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 엔드포인트와 관련된 정보를 입력합니다. 목록 형태의 값을 입력합니다.
데이터 모델 디자인 (components:)
URI Path 디자인 (paths:)
-
계층구조, 왼쪽이 상위 오른쪽으로 갈수록 하위
-
<
Resource>에는 Path 그 자체를 입력합니다. / 문자열로 시작합니다. -
<
Method>에는 HTTP 메소드를 입력합니다. get, post, put, delete 등이 될 수 있습니다. -
<
StatusCode>에는 응답 코드를 입력합니다. 이 때'200'과 같이 따옴표로 묶어서 써줘야 합니다. -
<
ContentType>에는 MIME 타입을 입력합니다.application/json이 보통입니다. -
<
DataModel> 은 앞서 언급한 데이터 모델 포맷을 넣을 수 있습니다.- 직접 넣거나,
- 또는 $ref 지시자를 이용해 참조로 넣을 수 있습니다.
-
데이터 모델을 참조로 하는 경우
-
요청이
GET /article이며, 이에 대한 응답이 성공적으로 도달한 경우 (200) 다음과 같은 JSON을 받게 된다고 가정해봅시다.
-
이 경우에 URL Path 디자인을 다음과 같이 할 수 있습니다. 데이터 모델에 Article이 이미 정의되어 있다고 가정한 코드입니다.
Learn About HTTPS
HTTPS 프로토콜
- Hyper Text Transfer Protocol Secure Socket layer
- HTTP over SSL(TLS), HTTP over Secure라고 부르기도 함
- HTTP 요청을 SSL 혹은 TLS라는 알고리즘을 이용해, HTTP 통신을 하는 과정에서 내용을 암호화하여 데이터를 전송하는 방법
암호화
- HTTPS 프로토콜의 특징 중 하나는 암호화된 데이터를 주고받기 때문에, 중간에 인터넷 요청이 탈취되더라도 그 내용을 알아볼 수 없음
- 비대칭 키 암호화, a키로 암호화 했다면 b 키로만 복호화 가능
인증서
- HTTPS 프로토콜의 또 다른 특징 중 하나는 브라우저가 응답과 함께 전달된 인증서 정보를 확인할 수 있다는 점
- CA = 공인 인증서 발급 기관, 브라우저별로 인증 기관이 다름
두 번째 발표
- 다음 기능에 대한 REST API 모범 사례를 연구해서 제출하세요.
특정 블로그 글에 달린 댓글 조회
GET /blogs/{blog_id}/comments
POST /posts/{postId}/comments: 게시글에 새로운 댓글 작성
PUT /posts/{postId}/comments/{commentId}: 게시글의 댓글 수정
DELETE /posts/{postId}/comments/{commentId}: 게시글의 댓글 삭제
기타 (어떤 메소드가 적합한지 고민해보세요!)
PUT /users/{userId}/profile: 특정 사용자의 프로필 수정
DELETE /posts/{postId}: 게시글 삭제
POST /signup: 새로운 사용자 회원가입
POST /login: 사용자 로그인
GET /search?query={query}: 검색어에 해당하는 게시글 목록 조회
블로그 글 좋아요
POST /blogs/{blog_id}/likes
블로그 글 좋아요 취소
DELETE /blogs/{blog_id}/likes
다른 글쓴이 팔로우
POST /users/{user_id}/follow
