REST API

REST API

Rest API (Representational State Transfer API) : 로이 필딩이 고안한, 웹의 장점 최대한 활용할 수 있는 아키텍처. 웹에서 사용되는 데이터나 자원(Resource)을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식. REST 원리를 따르는 시스템은 종종 RESTful이란 용어로 지칭된다. 열정적인 REST 옹호자들은 스스로를 RESTafrians 이라고 부른다.

 

Richardson 성숙도 모델(RMM) 

2단계까지만 적용해도 좋은 API 디자인(HTTP API) 

 

0단계 : HTTP 프로토콜 사용

 

1단계 : 리소스 중심의 올바른 엔드포인트 작성

• 요청하는 리소스가 무엇인지에 따라 각기 다른 엔드포인트로 구분. 엔드포인트 작성시 리소스에 집중해 정확한 명사 형태의 단어로 작성. 응답의 경우 사용한 리소스의 정보, 리소스 사용에 대한 성공과 실패 여부 반환
• 엔드포인트 활용법

<페이지네이션(pagination)으로 목록 끊는 기법> 
추가적인 필터링은 Query Parameter로 전달 
offset, limit 사용법 
GET /tweets?offset=10&limiit=10 //총 트윗 중 인덱스가 10~20인 트윗을 가져옴 
GET /tweets?offset=20&limiit=10 //총 트윗 중 인덱스가 20~30인 트윗을 가져옴 

<위치기반 한식당 찾기> 
GET /restaurants?coordinate=126.9178889,37.5561619&type=korean 
<다른 언어권에서 사용할 경우> 
Accept-Language 헤더를 요청에 함께 제공함 
기존의 엔드포인트 그대로 활용 클라이언트가 이해할 수 있는 언어 설정이 무엇인지 알려줌 
<삭제할 경우> 
애초에 엔드포인트에서 어떤 리소스를 삭제하는지 명시하는 것이 좋음 
DELETE /articles/10 //게시판에서 10번 게시물 삭제

• Query Parameter
  • Paging 예) ?page=1&per_page=30
  • Filtering 예) ?status=open
  • Sorting 예) ?direction=desc
  • Searching 예) ?q=javascript

 

2단계 : CRUD에 맞게 적절한 HTTP 메소드를 사용하는 것에 중점을 둠

응답 코드도 명확히 작성. 응답으로 생성된 리소스에 대한 내용을 응답 메시지의 본문(body)에 포함시켜야함.

요청
POST /seats/g10 HTTP/1.1
[헤더 생략]
{ "user": "kimcoding" }

정상 응답
HTTP/1.1 201 Created
[헤더 생략]
{ 
	"message": "예약이 성공적으로 진행되었습니다",
	"seat" : "g10",
	"user" : "kimcoding"
}

오류 응답
HTTP/1.1 409 Conflict
[헤더 생략]
{ 
  "message": "예약에 실패했습니다",
  "seat" : "g10",
  "status": "다른 사용자에 의해 예약됨"
 }

• GET : 서버의 데이터를 변화시키지 않는 요청에 사용
  • body가 존재하지 않으므로 Query Parameter 사용
• HEAD : status line, header만 조회함
• POST : 요청마다 새로운 리소스 생성(멱등성이 없음)
  • 멱등성(indempotence) :동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이 같은 효과를 지니고, 서버의 상태도 동일하게 남을 때
• PUT : 요청마다 같은 리소스 반환(멱등성이 있음). 교체할 때 사용
• PATCH : 수정할 때 사용
• OPTIONS : 소통 옵션 물어볼 때

 

3단계 : HATEOAS(Hypertext As The Engine Of Application State) 하이퍼미디어 컨트롤을 적용

요청은 2단계와 비슷하지만 응답에 리소스의 URI를 포함한 링크 요소를 삽입하여 작성하는 차이점. link에 하이퍼 미디어 컨트롤 포함.

<페이지네이션(pagination)으로 목록 끊는 기법> 
추가적인 필터링은 Query Parameter로 전달 
offset, limit 사용법 
GET /tweets?offset=10&limiit=10 //총 트윗 중 인덱스가 10~20인 트윗을 가져옴 
GET /tweets?offset=20&limiit=10 //총 트윗 중 인덱스가 20~30인 트윗을 가져옴 

<위치기반 한식당 찾기> 
GET /restaurants?coordinate=126.9178889,37.5561619&type=korean 
<다른 언어권에서 사용할 경우> 
Accept-Language 헤더를 요청에 함께 제공함 
기존의 엔드포인트 그대로 활용 클라이언트가 이해할 수 있는 언어 설정이 무엇인지 알려줌 
<삭제할 경우> 
애초에 엔드포인트에서 어떤 리소스를 삭제하는지 명시하는 것이 좋음 
DELETE /articles/10 //게시판에서 10번 게시물 삭제

API작성 레퍼런스

• 5가지의 기본적인 REST API 디자인 가이드
• 호주 정부 API 작성 가이드
• 구글 API 작성 가이드
• MS의 REST API 가이드라인
• gitHub 카카오나 네이버 토스 API 가이드라인 참고
• REST API 제대로 알고 사용하기

Open API

• • 기관마다 API 이용수칙, 제한 사항이 있음
  • 공공 데이터 포털 : 정부가 Open API 형태로 공공 데이터 제공
  • Open Weather Map
    • 제한적으로 무료 날씨 API 사용 가능
    • 데이터를 JSON형태로 응답
• API Key : API를 이용하기 위해 필요. 서버의 문을 여는 열쇠. 로그인된 이용자에게만 자원에 접근할 수 있는 권한을 API Key 형태로 제공하고, 데이터를 요청할 때 API key를 같이 전달해야 원하는 응답을 받을 수 있음