[Network] REST API

What is a API

API는 application programming interface의 약자로, 어떻게 통신이 이루어져야 하는가에 대한 약속이다.

What is difference between an API and a Protocol

protocol과 다른 점은 protocol은 두 통신 대상 사이에서 어떻게 메시지를 보낼 것인가에 대한 syntax를 포함한 통신 규약을 의미한다. 반면 API는 데이터를 통신하는 데에 이용하는 interface를 의미한다. ^[각주:1]

---

What is REST API

REST는 Representational State Transfer의 줄임말이다. REST는 protocol이나 표준이 아닌 architecture style이다. 따라서 API는 다양한 방식으로 구성될 수 있다. 따라서 높은 자유도를 가지기 때문에 microservices 등에서 널리 사용되게 되었다.

REST Design Principles

REST는 어떤 언어로 개발되어도 된다. 6개의 디자인 규칙만 만족하면 RESTful한 것으로 인정된다.

1. Uniform한 인터페이스
   같은 리소스에 대한 API request는 같아야 한다. 리소스는 너무 커서는 안 되지만 client가 필요한 데이터를 포함하고 있어야 한다.
2. Client-server 비연결
   REST API 디자인에서 client와 server application은 완전하게 독립적인 것이다. client가 알아야 하는 것은 requested resouce의 URI(Uniform resource identifier) 뿐이다. client는 URI 이외의 방법으로 server와 소통할 수 없다.
   server application도 마찬가지이다. HTTP로 requested data를 넘겨주는 것 이외에 client application을 수정할 수 없다.
3. Statelessness
   REST API는 stateless해야 한다. 즉, server application은 client request와 관련된 어떠한 데이터도 저장하는 것이 허락되지 않는다. 또한 각각의 request는 독립적으로 처리된다.
4. Cacheability
   가능하면, 리소스는 캐시 가능해야 한다. 원문 Cacheability. When possible, resources should be cacheable on the client or server side. Server responses also need to contain information about whether caching is allowed for the delivered resource. The goal is to improve performance on the client side, while increasing scalability on the server side.
5. 계층화된 시스템 아키텍처
   REST API에서, call과 response는 다른 layer를 거친다. client와 server가 직접 연결될 것이라고 추측해서는 안 된다. 즉, server의 각 유형을 client가 볼 수 없도록 계층 구조로 체계화되어야 한다.
6. Code on demand(optional)
   REST API는 보통 정적인 리소스를 전송하지만, response는 때때로 실행 가능한 코드일 수 있다. 이런 경우 client가 요청하면 server에서 실행 가능한 코드를 보낼 수 있어야 한다.

Design Tip

URI는 정보의 자원을 표현한다. 자원에 대한 행위는 HTTP method로 표현된다.^[각주:2]

How REST APIs work

REST API는 HTTP request를 통해서 생성, 읽기, 수정, 삭제(각각 creating, reading, updating, deleting으로 CRUD라고도 한다)가 이루어진다. 이는 POST, GET, PUT, DELETE로 이루어진다.

POST : 리소스를 생성한다.
GET : 해당 리소스를 조회한다.
PUT : 해당 리소스를 수정한다.
DELETE : 해당 리소스를 삭제한다.

EndPoint

웹 서비스의 endpoint는 client application에 의해서 리소스에 접근할 수 있도록 하는 URL이다.

---

HTTP Status

HTTP 상태 코드를 이용해서 HTTP 요청이 성공했는지 실패했는지 알려준다.

2XX Success

server가 client의 요청을 성공적으로 처리했다는 의미이다.

200 OK

클라이언트의 요청을 서버가 정상적으로 처리했다.

201 Created

클라이언트의 요청을 서버가 정상적으로 처리했고 새로운 리소스가 생겼다.

202 Accepted

클라이언트의 요청은 정상적이나, 서버가 아직 요청을 완료하지 못했다.

204 No Content

클라이언트의 요청은 정상적이다. 하지만 컨텐츠를 제공하지 않는다.

---

4XX Client errors

4XX는 클라이언트의 요청이 유효하지 않아 서버가 해당 요청을 수행하지 않았다는 의미이다.

400 Bad Request

클라이언트의 요청이 유효하지 않아 더이상 작업을 진행하지 않는 경우

401 Unauthorized

클라이언트가 권한이 없기 때문에 작업을 진행할 수 없는 경우

403 Forbidden

클라이언트가 권한이 없기 때문에 작업을 진행할 수 없는 경우

404 Not Found

클라이언트가 요청한 자원이 존재하지 않는 경우

405 Method Not Allowed

클라이언트의 요청이 허용되지 않는 메소드인 경우

409 Confilct

클라이언트의 요청이 서버의 상태와 충돌이 발생한 경우

429 Too Many Requests

클라이언트가 일정 시간 동안 너무 많은 요청을 보낸 경우

---

5XX Server errors

5XX 상태 코드들은 서버 오류로 인해 요청을 수행할 수 없다는 의미이다.

---

References

meetup
https://www.redhat.com/ko/topics/api/what-is-a-rest-api
https://www.ibm.com/cloud/learn/rest-apis
https://velog.io/@kho5420/Web-API-%EA%B7%B8%EB%A6%AC%EA%B3%A0-EndPoint
이상학의 개발블로그

1. https://www.quora.com/What-is-the-difference-between-an-API-and-a-Protocol [본문으로]
2. https://meetup.toast.com/posts/92 [본문으로]