RESTful Tutorial!
이 글은 RESTful에 대하여서 완벽하게 정리하는 것이 아닌 기본적인 내용을 학습하도록 작성한 글입니다.
세세한 내용에 대해서는 각 목차를 Keyword로 검색하시길 바랍니다.
해당 예제들은 다음 글에서 업로드할 예정입니다.
Notion에서 작성하고 옮겨오다 보니 몇몇 양식이 깨져있을 수 있습니다. 그렇기에 Notion Link도 남겨드립니다. www.notion.so/Week_02-01-REST-8d07b91683d548c2aa4e20f2f404eeef
RESTful을 위한 사전 지식
HTTP (Hypertext Transfer Protocol)
Web client와 Server 간의 데이터 전송을 위해 사용되는 Application Layer Protocol입니다.
요청과 응답을 하나의 트랜잭션 단위로 묶어놓고, 응답 이후에는 별도의 정보나 상태를 가지지 않는 Stateless Protocol이고, 데이터를 평문으로 전송되게 구현되어 있습니다.
사용 시 고려해야 할 점
- Stateless 하기에 상대적으로 서버의 Resource를 적게 사용할 수도 있으나, TCP Connection에 대한 Overhead가 심화될 수 있기에 이를 최적화하기 위한 여러 방법을 고려해야 합니다.
- 데이터가 평문으로 전송되기에 패킷 탈취, 변조에 대한 보안 공격에 취약점을 가지기에, HTTP Over SSL(HTTPS)과 같은 방법을 사용하여야 합니다.
추가적으로 학습할 Keyword로는 Handshaking, HTTP 구조와 1.1, 2.0, quic 정도가 있습니다.
HTTP Method
- GET (멱등성 O)
- Resource를 조회하는 상황에서 사용하는 HTTP Method입니다. 이 요청에 대해서는 캐싱이 가능하고 요청 Body가 기본적으로 제공되지 않습니다. 이는 요청 Body를 이용할 수 있음을 의미합니다.
- 몇 번을 요청하더라도 호출의 결과는 같기에 멱등성을 지킨다고 이야기합니다. 이 요청을 통해 받을 수 있는 State code는 200, 400, 404 등이 있습니다.
- POST (멱등성 X)
- Resource를 생성하는 상황에서 사용하는 HTTP Method입니다. 이 요청에 대해서는 캐싱이 가능하고 요청 Body가 존재합니다. 해당 요청 시 Resource를 만들 수 있는 충분한 정보를 가져야 합니다.
- 요청 시마다 새로운 Resource가 생성되기에 멱등성을 지키지 못한다고 이야기합니다. 받을 수 있는 State code는 201, 204 등이 있습니다.
- DELETE (멱등성 O, X)이 요청은 구현 방식에 따라 멱등성을 지킬 수도 있고, 지키지 못할 수도 있습니다. 기본적인 제약으로는 멱등성을 지킨다고 하는데, 이를 만족시키기 위해서는 해당 요청에 따라 Resource가 바로 삭제되는 것이 아닌 Flag 등을 통한 Soft Delete가 되어야 합니다.
- Resource를 삭제하는 상황에서 사용하는 HTTP Method입니다. 이 요청에 대해서는 캐싱이 불가능하고 요청 Body가 존재하지 않습니다.
https://tools.ietf.org/html/rfc7231#section-4.3.5
If the target resource has one or more current representations, they
might or might not be destroyed by the origin server, and the
associated storage might or might not be reclaimed, depending
entirely on the nature of the resource and its implementation by the
origin server (which are beyond the scope of this specification).
- PUT (멱등성 O)
- Resource를 전체적으로 수정할 때 사용하는 HTTP Method입니다. 이 요청에 대해서는 캐싱이 불가능하고 요청 Body가 존재합니다.
- 이 요청은 Resource가 존재한다면 모든 정보를 수정하고, 존재하지 않는다면 새로운 Resource를 생성하게 됩니다. 즉 POST와 같이 Resource 생성 시 필요한 모든 정보를 포함하고 있어야 합니다.
- PATCH (멱등성 X)
- Resource의 일부 정보를 수정하기 위해 사용하는 HTTP Method입니다. 이 요청에 대해서는 캐싱이 가능하고 요청 Body가 존재합니다.
- 이 요청은 Resource가 존재한다면 일부 정보를 수정하고, 존재하지 않는다면 Update 되지 않을 수 있습니다. 매 실행마다 다른 결과를 받을 가능성이 존재하기에 기본적으로 멱등하지 않다고 이야기합니다.
- 해당 방식을 PUT과 동일한 방식으로 작성한다면 멱등성을 가질 수 있게 될 수도 있습니다. https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/PATCH
이외에도 알아볼 Keyword로는 HEAD, CONNECT, OPTIONS, TRACE 등이 있습니다.
HTTP Status
HTTP Protocol은 Status Code를 정의, 제공하기에 요청 Client에게 State를 알려줄 수 있습니다.
1xx 번대
- 100 Continue
- 임시 응답, Client 가 요청하거나 요청이 완료된 경우에는 무시해도 되는 코드입니다.
- 101 Switching Protocol
- 서버에서 통신 Protocol을 변경할 것임을 알려줍니다.
- 102 Processing
- 서버가 요청에 대해서 처리 중이지만, 아직 응답할 수 없음을 알려주는 코드입니다.
2xx 번대
- 200 OK
- 메서드에 따라 의미가 변경되는 code로써 일반적으로 요청이 성공적으로 진행되었다는 의미입니다.
- 201 Created
- 요청이 성공적이었고, 그에 따른 새로운 Resource가 생성되었다는 의미입니다.
- 204 No Content
- 요청은 성공적이었으나, 서버에서 제공할 Content는 존재하지 않는다는 의미입니다.
3xx 번대
- 300 Multiple Choice
- 요청에 대해 하나 이상의 응답이 가능함을 의미하고, Client는 응답 방식을 선택하여야 합니다.
- 301 Moved Permanently
- 요청한 Resource의 URI가 변경되었음을 의미합니다.
- 303 See Other
- 요청한 Resource에 대해 다른 URI로 GET 요청을 보내야 함을 알려주는 것입니다.
4xx 번대
- 400 Bad Request
- 잘못된 요청 정보에 의하여 서버가 해당 요청을 처리할 수 없음을 의미합니다.
- 401 Unauthorized
- 해당 요청이 인증되지 않았음을 의미합니다. 이 Resource에 접근하기 위해서는 인증이 필요합니다.
- 403 Forbidden
- 해당 요청이 인가되지 않았음을 의미합니다. 이 Resource에 접근하기 위한 권한이 부족합니다.
- 404 Not Found
- 해당 요청에 대해서 해당하는 Resource를 찾지 못했음을 의미합니다.
- 405 Method Not Allowed
- 해당 요청에 따른 메서드가 존재하나, 현재 사용할 수 없음을 알려줍니다. 제거된 경우도 포함합니다.
5xx 번대
- 500 Internal Server Error
- 서버가 현재 요청을 처리하지 못하는 상황이거나, 처리할 수 없는 요청임을 의미합니다.
- 502 Bad Gateway
- 서버가 요청을 처리하는데 필요한 응답이 잘못 수신되었음을 의미합니다.
- 503 Service Unavailable
- 서버가 요청을 처리할 준비가 되지 않은 상태임을 의미합니다.
API
운영체제나 프로그래밍 언어가 제공하는 기능 등에 대해 제어할 수 있게 만든 인터페이스입니다.
API의 종류
- Private API
- 자사 제품, 서비스를 개선하기 위해 내부적으로 발행(구현)하는 API입니다. 외부에 노출되지 않습니다.
- Public API
- 개방형 API로써 모두에게 공개되는 API입니다. Kakao OpenBuilder나 Map API 등이 있습니다.
- Partner API
- 기업이 데이터 공유에 동의한 특정 기업, 사용자들에게 제공하는 API를 말합니다. B2B Solution가 이에 속할 수 있습니다.
Resource
리소스는 컴퓨터, 서버에 저장할 수 있는 모든 것을 포함할 수 있습니다.
이는 작성된 페이지, 문서, 이미지와 같은 Static Resource와 요청에 따른 논리적인 결과 값인 Dynamic Resource를 포함하는 개념입니다.
추가 학습 자료 : https://geobgu.xyz/web-mapping/web-servers-1.html#overview
URI
서버에서 제공하는 Resource는 식별자로 관리되고 접근할 수 있습니다. 이를 URI라고 합니다.
Client는 URI를 이용하여 서버에게 필요한 Resource에 대한 제공 요청을 할 수 있습니다.
URI 종류
- URL (Uniform Resource Locator)http://www.oreilly.com/index.html , http://www.naver.com/index.html
- URL은 특정 서버의 한 Resource에 대한 구체적인 위치를 서술합니다.
- URN (Uniform Resource Name)urn:examle:index
- Resource의 위치에 영향받지 않는 유일무이한 식별 값의 역할을 합니다.
Represent
표현은 Client에게 Resource를 어떻게 제공할 것인지에 대한 개념입니다.
서버는 XML, JSON, CSV, YAML, TEXT 등 여러 Format을 Client의 요청에 맞게 표현하여 제공해야 합니다. Client는 Content-Type Header를 통해 제공받을 Format을 정의할 수 있습니다.
JSON
JavaScript Object Notation은 데이터를 저장, 전송할 때 사용되는 경량 Data Format입니다.
JavaScript 에서 작성되는 Object 형식을 사용하였기에 JSON이라고 명명되었습니다.
Format Example
{
"id" : "1",
"name" : "lob",
"email" : "test@email.com"
}이와 같이 Key : Value Format을 사용합니다. 추가적으로 UTF-8 Encoding을 제공하며, 별도의 주석을 제공하지 않습니다.
Client-Server Model
Resource 요청자와 Resource 제공자 간에 작업을 분리하는 분산 애플리케이션이자 네트워크 아키텍처를 의미합니다. 일반적으로 웹 페이지 ↔ 서버 관계를 말합니다.
이외에도 알아볼 Keyword로는 DNS, Router, TCP/IP, UDP, Packet 등이 있습니다.
REST이란? (REpresentational State Transfer)
REpresentational State Transfer : 리소스의 상태를 표현하고 전송한다.
REST란 WWW과 같은 분산 하이퍼미디어 시스템에서 리소스와 상태를 표현하고, 전송하는 것에 대한 설계 양식입니다.
많은 사람들은 HTTP Protocol을 통해 REST를 구현하고 있지만, 이것은 HTTP에 종속되지 않는 개념입니다. 즉 다른 Protocol을 사용하거나 새로운 Protocol을 만들더라도 해당 설계 원칙을 지키면 "RESTful 하다."라고 말할 수 있음을 의미합니다.
해당 내용에 대해서는 CoAP RESTful API를 검색해보시면 좋을 것 같습니다.
REST의 6대 제약
Client-Server Model
Client - Server 아키텍처와 같이 독립적인 상태에서 구현되어야 하는 API 규약입니다.
Stateless
매 요청은 필요한 모든 정보를 담고 있어야 하며, 종료 시 상태는 없어야 한다.
Cache
SELECT - GET과 같은 조회성 트랜잭션은 캐싱하여야 한다.
Uniform Interface
제공되는 인터페이스는 일반적이고, 일관성이 있어야 하며, 간단할수록 좋습니다.
- Identification of resourcesREST API Design 항목 참고
- 각 Resource은 유일하게 식별 가능해야 하며, 개념적으로 분리되어야 합니다.
- Manipulation of resources through representationsClient는 매 요청에 대한 충분한 정보를 제공하여야 합니다. 수정, 조회, 삭제를 위한 데이터
- HTTP Method로 CRUD라는 표현을 담아야 합니다. URI에 담지 않습니다.
Example
GET "http://www.example.com/api/users" HTTP/1.1
PATCH "http://www.example.com/api/users/1224" HTTP/1.1이와 같이 URI 정보에는 CRUD 표현을 담지 않고, HTTP Message의 Method를 통해 표현해야 합니다.
- Self-describing messages
- 메시지 스스로 자신에 대한 설명이 가능해야 합니다.
- Resource를 제공할 때 Resource의 Type을 제공하고 (Content-type), Resource에 대한 링크를 Response Body에 포함함으로써 해당 조건을 만족할 수 있습니다.
- Hypermedia as the engine of application state (HATEOAS)
- 하이퍼 링크를 통해서 application의 상태 변화가 가능해야 합니다.
- Example
{
... ,
"_links": {
"self": {
"href" : "http://www.example.com/api/users/1334"
},
"prev-link" : {
"href" : "http://www.example.com/api/users"
}
}
}
위에 제시된 예시처럼 Link를 제공하여 페이지 이동 등을 할 수 있도록 지원하여야 합니다.
데이터에 대한 링크를 제공하는 것을 HAL이라고 합니다.
Layered System
계층적으로 구성되어야 하며, Client는 리소스에 직접 접근하지 않고 (Server를) 호출하여야 합니다.
이는 각각의 기능이 다른 계층으로 구성되고 각각의 계층은 인접한 계층에만 통신하며, 기능 수행을 위해 하위 계층을 의존해야 한다는 것을 의미합니다.
Controller ↔ Service ↔ Repository와 같은 구조도 Layered 아키텍처입니다.
Code-On-Demand (Optional)
Server가 Client에게 Code(JavaScript..)를 제공하여 확장을 할 수 있어야 합니다.
Richardson Maturity Model
이는 REST 제약에 부합되는 정도를 등급으로 매긴 것입니다. 일반적으로 RESTful API이라 명명할 수 있는 Level은 2 Level부터입니다.
level 0 : The Swamp of POX
HTTP를 데이터 전송을 위한 protocol로만 사용할 뿐 상태를 나타내거나 하지 않습니다.
POX 란 순수한, 평범한 XML를 주고받는 것을 의미하며, 이 level은 하나의 Endpoint를 제공하는 단순한 스타일의 API를 이야기합니다. 이러한 시스템을 RPC Model이라고 명칭 하기도 합니다.
이와 관련된 키워드는 SOAP, XML-RPC, RPC Model 등이 있습니다.
level 1 : Resource
서버의 Resource에 대한 각각의 point를 제공하는 상태의 API를 의미합니다.
모든 요청은 필요한 Resource에 대한 개별적인 point로 통신하는 상태이지만, 하나의 HTTP Method만을 사용합니다.
Example
POST "http://www.example.com/users" HTTP/1.1
POST "http://www.example.com/posts" HTTP/1.1
POST "http://www.example.com/locations" HTTP/1.1
level 2 : HTTP Verbs
HTTP Method와 Resource 동사를 결합하여 REST API를 온전히 제공하는 단계입니다.
HTTP Protocol의 능력을 최대한 활용한 상태라는 것은 각각의 HTTP Method를 골고루 활용하고 있음을 나타냅니다.
Example
GET "http://www.example.com/users" HTTP/1.1
POST "http://www.example.com/users" HTTP/1.1
DELETE "http://www.example.com/users/1223" HTTP/1.1
PATCH "http://www.example.com/users/1223" HTTP/1.1
level 3 : HATEOAS
Client와 동적인 상호작용이 가능한 상태의 REST API를 말합니다. 이는 Link를 통해 제공됩니다.
Uniform Interface : Hypermedia as the engine of application state 항목.
REST API Design
URI는 제공되는 Resource를 기준으로 작성해야 합니다.
복수 자원
두 개 이상의 Resource를 제공할 때 작성하는 방식입니다.
(post 정보들)
"https://www.example.com/api/posts"
(location 정보들)
"https://www.example.com/api/locations"
(user 정보들)
"https://www.example.com/api/users"
단일 자원
하나의 Resource를 제공할 때 작성하는 방식입니다.
(post들 중에 하나의 post)
"https://www.example.com/api/posts/{postId}" -> "api/posts/123"
(location들 중에 하나의 location)
"https://www.example.com/api/loacations/{locationId}" -> "api/loacations/123"
(user들 중에 하나의 user)
"https://www.example.com/api/users/{userId}" -> "api/users/123"
하위 리소스 표현
해당 Resource가 보유하고 있는 하위 Resource에 대해 작성하는 방식입니다.
( Customer들 중에 하나의 Customer 정보 )의( accounts 정보 들)
"https://www.example.com/api/customers/{customerId}/accounts"
( Customer들 중에 하나의 Customer 정보 )의( accounts 정보 들 중 하나의 accounts )
"https://www.example.com/api/customers/{customerId}/accounts/{accountsId}"
버저닝
변경 사항에 따른 API 버전 관리 방식입니다.
Semantic Versioning
{MAJOR}. {MINOR}. {PATCH} 형식으로 Version을 관리하는 방식을 의미합니다.
example) 1.0.1
버전 관리 방식의 종류
- URI을 통한 버전 관리
- https://www.example.com/api/{API VERSION}/users
- Query String를 통한 버전 관리
- https://www.example.com/api/users?version={API VERSION}
- Custom Header를 통한 버전 관리
- *"Accepts-version" : "1"*
- Content Negotiation를 통한 버전 관리
- *"Accepts" : "application/json; version={API VERSION}"*
REST 요소 : Document, Collection, Store, Controller
- Document위에서 설명된 단일 자원 표현이 이에 해당됩니다.
- https://www.example.com/api/users/{userId}
- 기본이 되는 Resource 형식을 의미합니다. 이는 데이터베이스의 Record를 검색하는 것과 유사합니다.
- Collection위에서 설명된 복수 자원 표현이 이에 해당됩니다.
- https://www.example.com/api/users
- Server에서 관리하는 Document들이 모여있는 Store를 의미합니다. 이는 데이터베이스의 Table를 검색하는 것과 유사합니다.
- Store복수로 작성되어야 합니다. profiles, favorites...
- https://www.example.com/api/users/favorites
- Client에서 관리하는 Resource Store를 의미합니다.
- Controllersign-up, buy
- https://www.example.com/api/users/sign-up
- Resource에 대한 CRUD 조작 이외의 의미들을 나타냅니다.
기타 규약
- 자원을 나타내는 명사만을 사용하여야 하며, 동사를 사용하지 않습니다.
- "/"를 통하여 계층 관계를 나타내어야 합니다. (맨 뒤에는 / 를 사용하지 않습니다.)
- 명사와 명사 사이에는 가독성을 위해 '-' (하이픈) 문자를 사용해야 합니다.
- '_'을 사용하지 않습니다. 이는 일부 브라우저나 화면에서 보이지 않을 수 있기 때문입니다.
- 소문자만을 일관적으로 사용하여야 합니다.
- 파일 확장자를 사용하지 말아야 합니다. 이는 어떠한 이점도 주지 않고 URI 길이만 늘어나게 하기 때문입니다.
해당 내용들을 읽은 후 공개 API 설계 시 도움이 될 수 있는 Keyword로는 OAS 3.0이 있습니다.
참고 자료
- https://ko.wikipedia.org/wiki/REST#:~:text=REST(Representational State Transfer)는,아키텍처의 한 형식이다.&text=필딩의 REST 아키텍처 형식,설계하는 것도 가능하다.
- https://restfulapi.net/
- RESTful Web API : 웹 API를 위한 모범 전략 가이드
'Next Step > 블랙커피 블로그 스터디' 카테고리의 다른 글
| RESTful API 02. 예제를 Spring Framework로 구현하기 (0) | 2021.01.31 |
|---|---|
| Week_01 : DB의 Index, 스터디 발표, Go 입문 (0) | 2021.01.24 |
