API란?
“Application Programming Interface”
앱에서 사용할수 있도록 운영체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 말한다.
REST란?
“REpresentational(표현가능한) State(상태) Transfer(전송)”
자원을 이름(표현)으로 구분하여 자원의 상태(정보)를 주고 받는 모든 것을 의미한다.
HTTP URI를 통해 자원을 명시하고, HTTP Method를 통해 해당 자원의 CRUD Operation을 적용하는것을 의미한다.
REST 구성
- 자원(Resource) : URI
- 행위(Verb) : HTTP Method
- 표현(Representations)
Restful API 특징
- Server-Client 구조
서버와 클라이언트를 구분함으로 의존성이 줄어든다. - Stateless
서버에서 상태정보를 저장하거나 관리하지 않기때문에, 들어오는 요청만 처리하면 된다. - Cacheable
웹에서 사용하는 기존 인프라를 그대로 활용하기 때문에 캐싱 기능을 사용할 수 있다. - Layered System
REST 서버는 다중계층으로 구성될 수 있다.(보안, 로드 밸런싱, 암호화계층)
PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있다. - Code-On-Demand(Optional)
Server로 부터 스크립트를 받아서 Client에서 실행된다. - Uniform Interface
리소스에 대한 조작이 통일되고 한정적인 인터페이스로 수행한다.
self-descriptive : REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체표현구조로 되어 있어야한다.
HATEOAS : 클라이언트가 서버에 요청시 서버는 요청에 의존되는 URI를 Response에 포함시켜 반환한다.
예를 들면, 사용자정보의 POST 요청 후 사용자를 GET, PUT, DELETE할 수 있는 URI를 동적으로 알려주게 되는 것이다.
REST API 설계 기본 규칙
첫 번째, URI는 정보의 자원을 표현해야 한다.
두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.
GET /rooms
DELETE /room/:id URI 설계시 주의할 점
- 슬래시(/)는 계층 관계를 나타내는데 사용한다.
http://restapi.example.com/room/:id- URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
- 하이픈(-)은 URI 가독성을 높여준다.
- 밑줄(_)은 URI에 사용하지 않는다.
- URI 경로에는 소문자가 적합하다.
- 파일확장자는 URI에 포함하지 않는다.
대신 Accept header를 사용한다. - 리소스 간에 연관관계가 있는 경우
리소스명/리소스ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices(일반적으로 소유 'has'의 관계를 표현할 때)
*Document : 하나의 객체
http://restapi.example.com/sports/soccer*Collection : 객체들의 집합(일반적으로 복수로 사용)
http://restapi.example.com/sports/soccer/players/13HTTP STATUS CODE
| STATUS CODE | DETAILS |
|---|---|
| 200 (OK) | 클라이언트의 요청을 정상적으로 수행 |
| 201 (Created) | 클라이언트가 어떤 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업시) |
| 301 (Moved Permanently) | 클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 응답 코드 |
| 400 (Bad Request) | 클라이언트의 요청이 부적절 할 경우 |
| 401 (Unauthorized) | 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을때 |
| 403 (Forbidden) | 유저 인증상태와 관계없이 응답하고 싶지 않은 리소스를 요청했을때 |
| 404 (Not found) | 데이터가 있어야 하나 없음 |
| 405 (Method Not Allowed) | 클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 |
| 500 (Internal Sever Error) | 서버에 뭔가 문제가 있을때 사용하는 응답코드 |
representation in HTTP
HTTP에서의 representation
GET 메서드의 정의를 먼저 살펴보면
The GET method requests transfer of a current selected representation
for the target resource.target resource에 대한 현재 선택된 representation 하나를 반환한다.
“target resource” 란?
-> uri가 가리키는 리소스이다.
그렇다면 리소스란 무엇인가?
-> HTTP 요청의 대상이다.
“representation” 란? (representation data 와 representation metadata로 구성)
-> 어떤 리소스의 특정 시점의 상태를 반영하고 있는 정보이다.
“선택된” 이란?
하나의 리소스의 현재 representation이 하나 이상이 될 수 있으며, 그 중 하나가 선택되었음을 의미한다.
representation들의 예시)
영어 사용자를 위한 representation:
Content-Type: text/plain
Content-Language: en
hello한국어 사용자를 위한 representation:
Content-Type: text/plain
Content-Language: ko
안녕하세요HTML을 선호하는 영어 사용자를 위한 representation:
Content-Type: text/html; charset=UTF-8
Content-Language: en
<html><body>hello</body></html>HTML을 선호하는 한국어 사용자를 위한 representation:
Content-Type: text/html; charset=UTF-8
Content-Language: ko
<html><body>안녕하세요</body></html>그러면 이들 중 하나를 선택 하는 것은 누가 어떻게 할까?
클라이언트와 서버간의 Content negotitaion을 통해 선택하며, 선택의 주체는 협상 방법에 따라 다르다.
사전 협상의 경우 서버가 선택하고, 클라이언트가 어떤 문서를 선호하는지 헤더에 포함시켜 전송한다.
여기서, 여러 리소스중 하나가 선택되었다고 말할 수 있을까?
위의 요청 모두 같은 uri를 갖기 때문에 같은 리소스이다. 그렇기 때문에, 여러 리소스 중 하나가 선택되었다고 말할 수 없다.
예외) 클라이언트가 선택하는 사후협상의 경우는 리소스중 하나를 선택한다고 볼수도 있다.
representation in REST
State는 웹 애플리케이션의 상태, Transfer는 이 상태의 전송을 의미한다.
웹페이지 A를 보고있던 사용자가 웹페이지 B로 가는 링크를 클릭하면, 웹브라우저는 링크가 가리키는 웹페이지 B를 렌더링해서 보여줄 것이다.
링크를 클릭함으로써 브라우저가 보여주던 페이지는 A에서 B로 바뀌었다.(웹 애플리케이션의 상태 변경) 이 상태의 변경은 representation의 전송을 통해 이뤄졌다.
여기서 주의할 두가지는,
1. Transfer는 상태의 전이를 의미하는 것이 아니다. 전이가 아니라 network component 사이에서의 전송을 말한다. 즉, 여기서는 서버에서 클라이언트로의 웹 페이지 전송을 의미하는 것이다.
- 리소스의 상태와 애플리케이션의 상태는 둘다 state로 표현되고 있긴 하지만, 본질적으로 완전히 다른 것이다. 앞에서 representation이란 어떤 리소스의 특정 시점의 상태를 반영하고 있는 정보라고 말했다. 이것은 리소스의 상태이지 애플리케이션의 상태는 아니다. 애플리케이션의 상태란, 웹애플리케이션이 웹 페이지 A를 렌더링하다 B를 렌더링하는것으로 바뀐 그 상태를 말한다.
모든 payload는 representation
Reference
