42page

REST API

April 13th 2019

**차례** - What is API? - What is REST API? - REST six contraints - RESTful convention - Limitation of REST

What is API?

API는 Application programming interface의 약자입니다. 우리가 데이터를 요청하고 받는 다양한 상호작용을 API를 이용해 할 수 있습니다. 이러한 데이터 상호 작용을 위해 클라이언트와 서버가 요청을 주고 받는 사이클이 만들어 지는데 이를 HTTP Request라고 합니다. 유효한 HTTP request가 되기 위해서 URL, METHOD, LIST OF HEADERS, BODY 네 가지를 갖춰야 합니다.
URL은 사이트에 접속을 하기 위한 주소를 말합니다. METHOD를 통해서는 클라이언트가 서버에 어떠한 작업을 진행하길 원하는지 전달할 수 있습니다. 가장 일반적인 네 가지 METHOD는 GET, POST, PUT, DELETE가 있습니다. 그리고 HEADER에는 request와 관련된 여러 meta 정보가 포함되어 있습니다. 그리고, BODY에는 서버측에 전달하고자 하는 데이터를 포함할 수 있습니다.

과거 웹 애플리케이션에서 클라이언트가 웹페이지 상에서 어떠한 새로운 정보나 또는 수정을 요청하면, 서버는 그러한 요청을 받아들여 완전히 새로운 페이지를 전달했습니다. 이를 전달 받은 웹 브라우저는 새 페이지를 로드해야 했습니다. 이후 XMLHttpRequest가 적용된 후, 페이지 전체의 로딩 없이 부족한 데이터만 서버로부터 가져올 수 있게 되었습니다. 이러한 데이터 상호작용에 API가 이용되었습니다. 그리고 가장 일반적인 데이터 포맷으로는 XML과 JSON 두 가지가 있습니다.

참고로 API의 약자 중 interface는 UI 또는 GUI와는 관계가 없습니다. 여기서 말하는 interface는 property와 methods의 리스트를 의미한다고 생각하는 것이 더 좋은 것 같습니다.

What is REST API?

REST란 웹을 위한 네트워크 기반의 아키텍쳐 스타일이고, 그 스타일을 따르는 아키텍쳐가 지켜야 하는 제약 조건들입니다.

웹이 처음 만들어 졌을 때는 지금처럼 엄청나게 많은 사용자를 염두에 두고 만들어지지 않았다고 합니다. 이후 웹이 네트워크 수단으로 지속적으로 성장하자, 초기의 웹 선구자들이 웹에 대한 규약을 만들어, 웹이 지속적으로 성장할 수 있도록 하고자 했습니다. 이 REST의 6가지 규약은 아래와 같습니다.

REST six contraints

- Uniform Interface - Client-server - Stateless - Layered System - Cacheable - Code on Demand

Uniform Interface 서버에 요청을 보내는 request는 요청을 하는 resource에 대한 identifier를 포함해야 합니다.

Client-server 클라이언트와 서버는 독립적입니다. 즉, 둘은 서로가 어떻게 구현되는지 알 지 못하고, 일관된 규칙에 의해서 통신을 한다는 뜻입니다. 클라이언트와 서버가 독립되어 있기 때문에 확장성이라는 장점을 가질 수 있습니다.

Stateless Stateless란 서버가 api를 이용한 user에 대한 정보를 기억하지 않는다는 뜻입니다. 누가 과거에 get 요청을 보냈는지, 이전에 동일한 자원을 요청한 이력이 있는지 등에 대한 정보를 기억하지 않습니다. 각각의 요청은 서버가 필요한 모든 정보를 가지고 있기 때문에 해당 요청에만 근거로 서버는 응답을 합니다.

Layered System 클라이언트와 서버가 요청과 응답을 주고 받을 때, 중간에 네트워크 중간 매체가 존재할 수 있습니다. 하지만, 이러한 중간 layer들이 클라이언트와 서버의 요청 및 응답에 어떠한 영향을 미치지는 않습니다.

Cacheable Cacheable이란 서버가 보내는 데이터가 캐싱이 가능한지 불가능한지에 대한 정보를 포함하고 있는 것을 뜻합니다. 만약, 캐싱이 가능하다면 데이터의 버전에 대한 정보가 포함되었을 수 있습니다. 클라이언트가 이전 요청으로 받은 데이터의 버전을 확인해서 업데이트된 정보를 받기 위해 요청을 다시 보내야 할 지 알 수 있습니다.

Code on Demand Code-on-demand는 스크립트나 플러그인 같은 실행 가능한 프로그램을 일시적으로 클라이언트에 전송해, 클라이언트 측에서 실행할 수 있도록 하는 것입니다.

RESTful convention

RESTful API를 설계하기 위해 따라야 하는 여러 convention이 있습니다. 그 중 몇 가지 아래와 같이 소개하겠습니다. 참고로, convention을 따랐을 때 동반되는 장점은 동료나 다른 개발자들이 코드를 쉽게 이해할 수 있다는 것입니다.

Rest conventions or restful conventions are a predefined system for defining different routes on an API that work with a given type of records.
1. 동사 대신 명사 사용.
  1. GET method와 query parameter는 상태하지 않음. 어떠한 상태를 변경하려면, GET method 대신 PUT, POST, DELETE method 등을 사용해야 합니다.
  2. 복수 명사 사용 단수 명사와 복수 명사를 혼용 사용하지 말아야 합니다. 단순화해서 자원을 요청할 때 복수 명사를 사용하도록 합니다.
/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting
  1. 자원간의 관계 이용 어떠한 자료가 다른 자원과 상하관계가 있으면 이러한 관계를 이용해야 합니다.
GET /cars/711/drivers/ Returns a list of drivers for car 711
GET /cars/711/drivers/4 Returns driver #4 for car 711
  1. format 설정을 위해 HTTP Header를 이용 클라이언트와 서버가 통신 시 어떤 format을 사용할 지 알아야합니다. 이 format은 HTTP-header에 명시되어야 합니다. 'Content-type'은 요청 포맷을 정의하고, 'Accept'는 수용가능한 응당 포맷을 정의합니다.
  2. HATEOAS
  3. Collection에 대한 filtering, sorting, field selection, pagination 기능의 제공.

- Filtering: 각 필드 별 유니크한 query parameter 또는 query language를 사용

GET /cars?color=red Returns a list of red cars
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seats

- Sorting: 다중 필드에 대한 오름 또는 내림 차순의 정렬을 지원

GET /cars?sort=-manufactorer,+model

위의 정렬 방법은 manufacturer에 대한 내림 차순, 그리고 model에 대한 오름 차순으로 정렬을 합니다.

- Field selection: 모바일의 경우 축약된 기능만 화면에 보여줍니다. API를 이용하는 쪽에서 응답 받을 field를 선택하게 할 수 있도록 설계를 해야 합니다. 이것은 또한 network traffic을 줄이고, API 이용 속도를 향상시킬 수 있습니다.

GET /cars?fields=manufacturer,model,id,color

- Paging: paging을 위해 limit과 offset를 사용하지만, 이에 대한 기준은 유연합니다. Default는 limit=20, offset=0이 됩니다.

  1. Version your API - API version에 대한 표기를 합니다.
//example
/blog/api/v1
  1. 에러는 HTTP status code와 함께 처리 API를 다룰 때 에러 핸들링을 잘 하는것은 중요합니다.
  2. HTTP Method의 overriding 허용 일부 proxies는 POST와 GET만을 support합니다. 이러한 제약조건이 있을때 RESTful API를 지원하기 위해서는 HTTP Method를 override 할 수 있도록 허용해 주어야 합니다. X-HTTP-Method-Override를 Header에 추가해 주어야 합니다.

Limitation of REST

추후 업데이트(정리중..;;)

© Chanwhe Kim 2019

Handmade with .