클라이언트 시점에서 보는 RESTful API
11.1 RESTful API
REST는 2000년에 네트워크 기반 아키텍처 논문에서 발표되어, 웹 애플리케이션같 연계를 위해 많이 사용되고 있습니다. 이는 HTTP 신택스를 프로토콜의 토대로 사용했습니다.
다음과 같은 특징을 지닙니다.
•
API가 웹 서버를 통해 제공
•
GET/user/[userID]처럼 경로에 메서드를 보내 서비스를 얻음
•
API 성공여부를 스테이터스 코드로 클라이언트에 제공
•
URL은 리소스의 위치를 나타내는 표현
•
서버에서 오는 반환값으로 JSON, XML 등 구조화 텍스트나 이미지 데이터 반환
클라이언트에선 서버에 아래와 같은것을 기대할 수 있습니다.
•
URL은 리소스의 계층을 나타낸 경로로 명사로 구성
•
리소스에 대해 HTTP 메소드를 보내 리소스 취득, 갱신, 추가등 작업
•
스테이터스 코드를 보고 요청 처리여부 판단
•
GET은 상태를 변경하지 않음
•
클라이언트 쪽에선 상태를 관리하지 않고, 요청을 독립적으로 발행
•
트랜잭션은 없음(SQL을 통해 DBd에 접근하지 않음)
이러한 REST 원칙을 지킨것을 RESTful하다고 표현합니다.
11.1.1 REST API와 RPC 차이
RPC의 경우 URL은 하나로 요청할 때 서비스 이름과 메서드 이름을 전달해 ‘무엇을 할 것인가’를 지정합니다. REST는 정보를 갱신할 때 수정된 리소스를 첨부해서 ‘이걸로 덮어쓰라’고 전송합니다.
11.1.2 Web API와 트랜잭션
RPC의 경우 트랜잭션과 비슷한 API를 제공할 수도 있지만, 트랜잭션이 필요한 단위로 원자적인 API를 제공하는것이 현재 현실적입니다. JSON-RPC는 여러 요청을 배열로 모아 호출하는데, 이를 통해 간단한 트랜잭션을 다룰 수 있습니다. 이는 가급접 웹 API를 한번에 끝내는게 중요합니다. 이는 HTTP도 순서를 보증할 수 없기 때문에 한번에 처리하는게 중요합니다.
11.1.3 HATEOAS
HATEOAS는 REST의 일부인 ‘인터페이스의 일반화’를 사양으로 만든 것입니다.
XML 중 <link> 태그로 주어진 정보가 HATEOAS를 위해 추가된 것으로 여기엔 오브젝트에 대해 실핼할 수 있는 작업과 관련 오브젝트의 링크를 포함합니다. 이를통해 클라이언트는 홈페이지에서 데이터와 작업을 나타내는 목록을 얻을 수 있어, API에 대한 사전지식이 없어도 충분히 사용할 수 있습니다.
11.1.4 RESTful와 REST-ish
REST API는 HTTP의 신택스와 시맨틱스를 지키는 것을 이상적이라 봅니다. 이는 라이브러리 등을 통해 쉽게 지킬 수 있지만, URL의 리소스 구조나 메서드 선택 등을 일치하지 않을 수 잇습니다.
예를들어, URL에 동사, /api문자, 포맷을 나타내는 문자(/json), 버전이 들어가는 경우 등이 있습니다. 그러나 이는 마소에서조차도 못 지킬만큼 어려운 일입니다.
이를 위해 REST-ish API라고 부르는 방법이 있습니다.
11.2 메서드
기본적으로 사용하는 메서드는 7종류가 있습니다.
•
TRACT, CONNECT : API 엑세스에는 사용하지 않습니다.
•
PATCH : 사용은 가능하지만, 거의 사용하지 않습니다.
•
HEAD : 헤더만 가져옵니다.
•
OPTIONS: 프리플라이트 요청에 사용
HTTP 사양에서 메서드 분류에는 안전과 멱등이라는 두가지 지표가 있습니다. 안전은 실행해도 리소스를 변화시키지 않는 것입니다. 멱등은 서버의 리소스는 변경되지만 몇번을 실행해도 결과가 바뀌지 않는 것입니다.
안전한 메서드: GET, HEAD, OPTIONS
멱등한 메서드: PUT, DELETE
HTML의 폼은 GET과 POST만 지원하고있고, 이들만 이용하는 서버도 있습니다. 또한 PUT, DELETE를 메시지에만 싣고, 실제는 POST를 사용할 수 있습니다. 이를 오버로드 POST라고 부릅니다. 구글의 API 디자인 가이드에선 경로 뒤에 :메서드 이름 문자열을 추가해 표현하는 것을 제안합니다.
11.3 스테이터스 코드
11.3.1 100번대(정보)
성공이나 실패가 결정되기 이전 상태입니다. 또한 바디를 포함하지 않습니다.
•
100 Continue : 송신하기 전에 헤더만 보내서 허기를 구하러 온 클라이언트에 서버가 접수했다는 사실을 전달
•
101 Switching Protocols : 클라이언트가 의뢰한 HTTP이외의 프로토콜로 변경을 서버가 접수했을 때 반환됩니다. API에서는 사용되지 않습니다.
•
103 Early Hints : HTTP/2에서 서버 푸시를 위한 힌트 정보를 반환하며 책정 중입니다.
11.3.2 200번대(성공)
•
200 OK: 정상 종료
•
201 Created: POST 메서드에 대해 반환될 가능성이 있으며, 작성에 성공했을 때 반환
•
202 Accepted : 서버는 접수했지만, 실제 처리가 완료되지 않은 때 반환
•
203 NonAuthoritative Information : 요청 자체는 성공했지만, 중계 프록시가 신뢰할 수 없는 정보로서 부여
•
204 No Content: DELETE 메서드에 대해 반환될 가능성
•
205 Rest Content : 서버에서 클라이언트으 ㅣ화면을 재설정하고 초기 상태로 하도록 요청
•
206 Partial Content: 다운로드 중단 및 재개에서 사용되는 상태 코드
11.3.3 300번대(리다이렉트)
리디렉션 및 캐시의 변경이 없을 때 사용합니다. 거의 사용하지 않습니다.
•
305 Use Proxy : 현재는 추천되지 않습니다.
11.3.4 400번대(클라이언트 오류)
요청할 URL이 틀렸거나 필요한 헤더가 부족할때, 바디의 형식이 틀렸을 때 반환
•
400 Bad Request : 클라이언트 요청에 문제가 생길 때 반환 및 기타 항목에 포함되지 않은 경우
•
401 Unauthorized : 인증이 필요
•
402 Payment Required : (RFC에 사양 미존재) 금전 지불이 필요 시 반환
•
403 Forbidden : 금지된 액세스에 반환하며 404로도 사용
•
404 Not Found : 리소스를 찾을 수 없음
•
405 Method Not Allowed : 허용되지 않은 메서드 사용
•
406 Not Acceptable : 콘텐트 니고시에이션 결과로 서버와 클라이언트 양쪽이 이해할 수 없는 형식인 경우
•
407 Proxy Authentication Required : 프록시 인증 필요
•
408 Request Timeout : 서버가 기다렸지만, 요청이 기대한 대로 오지 않았을 때
•
409 Conflict : 동시에 쓰는 서버가 요청을 수행할 때 충돌이 일어나 정상적으로 처리가 이루어지지 않았을 때 반환
•
410 Gone : 원래 있었던 리소스가 없어졌을 때 반환하며 404로도 사용
•
411 Length Required : 필요한 콘텐츠 길이 미지정
•
412 Precondition Failed : 사전 조건에 실패
•
413 Payload Too Large : 바디 크기가 서버의 허용치 초과
•
414 URI Too Long : URL 길이가 서버의 허용치 초과
•
415 Unsupported Media Type : 지정된 미디어 타입 미지원
•
416 Range Not Statisfiable : 다운로드에서 지정된 범위가 무효
•
417 Expectiation Failed : Expect 헤더는 바디 송신 확인에서 소개한 100-Continue 이외의 값만 허용
•
421 Misdirected Request : 서버에 요청된 스키마가 지원하지 않을 때 반환
•
426 Upgrade Required : 다른 프로토콜로 변경하도록 클라이언트에 요청
•
428 Precondition Required : 사전 조건이 틀렸을 때로 사전 조건은 변경 전 데이터의 ETag를 가정
•
429 Too Many Requests : 대량의 요청을 보냈을 때 요류
•
431 Request Header Fields Too Large : 요청 헤더가 클 때
•
451 Unavailable For Legal Reasons : 법적인 이유로 접근 거부
11.3.5 500번대(서버 오류)
서버 오류 입니다.
•
500 Internal Server error :서버 내부 오류
•
501 Not Implemented : 서버 기능 미구현
•
502 Bat Gateway : 게이트웨이나 프록시 서버가 요청으 럭부, 로드밸런서가 거부한 경우도 포함
•
503 Service Unavailable : 서버가 시작되지 않은 경우 프록시와 로드밸런서가 반환
•
504 Gateway Timeout : 게이트웨이나 프록시 서버가 최종 목적지 서버에 도달할 수 없어 타임아웃됨
•
505 HTTP Version Not Supported : 지원하지 않는 HTTP 버전 요청
•
509 Bandwidth Limit Exceeded : 통신 대역폭을 다 썻을 때
11.4 바디
웹 API 초기엔 XML이 대다수였지만, 최근엔 JSON이 많아졌습니다.
