책소개

사전처럼 찾아 쓰는 REST API 규칙과 팁

사람들의 관심을 끌기 위해 경쟁하는 웹 서비스 시장에서, 잘 설계된 REST API는 꼭 지녀야 할 특징이 되고 있다. 이 책은 REST 아키텍처 스타일을 잘 살린, 실제 사례에서 도출한 REST API 디자인 규칙을 제공한다. REST API 규칙과 팁이 사전처럼 잘 정리되어 있으므로 필요한 부분만을 찾아서 사용할 수 있다. 제공하는 규칙에 따라 URI를 설계하면, 일관된 REST API를 웹 서비스에 적용할 수 있을 것이다.

저자소개

목차

1장. REST 소개
__01 Hello World Wild Web 
__02 웹 아키텍처 
____클라이언트/서버 
____균일한 인터페이스 
____계층 시스템 
____캐시 
____상태 없음 5
____주문형 코드 
__03 웹 표준 
__04 REST 
__05 REST API 
__06 REST API 설계 
____규칙 
____WRML 
__07 정리 

2장. URI 식별자 설계
__01 URI 13
__02 URI 형태 
____규칙: 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다 
____규칙: URI 마지막 문자로 슬래시(/)를 포함하지 않는다 
____규칙: 하이픈(-)은 URI 가독성을 높이는 데 사용한다 
____규칙: 밑줄( _ )은 URI에 사용하지 않는다 
____규칙: URI 경로에는 소문자가 적합하다 
____규칙: 파일 확장자는 URI에 포함시키지 않는다 
__03 URI 권한 설계 
____규칙: API에 있어서 서브 도메인은 일관성 있게 사용해야 한다 
____규칙: 클라이언트 개발자 포탈 서브 도메인 이름은 일관성 있게 만들어야 한다 
__04 리소스 모델링 
__05 리소스 원형 
____도큐먼트 
____컬렉션 
____스토어 
____컨트롤러 
__06 URI 경로 디자인 
____규칙: 도큐먼트 이름으로는 단수 명사를 사용해야 한다 
____규칙: 컬렉션 이름으로는 복수 명사를 사용해야 한다 
____규칙: 스토어 이름으로는 복수 명사를 사용해야 한다 
____규칙: 컨트롤러 이름으로는 동사나 동사구를 사용해야 한다 
____규칙: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다 
____규칙: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다 
__07 URI Query 디자인 
____규칙: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다 
____규칙: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 한다 
__08 정리 

3장. HTTP를 이용한 인터랙션 설계
__01 HTTP/1.1 
__02 요청 메서드 
____규칙: GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안 된다 
____규칙: GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다 
____규칙: 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야 한다 
____규칙: PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다 
____규칙: PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다 
____규칙: POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다 
____규칙: POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다 
____규칙: DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다 
____규칙: OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 한다
__03 응답 상태 코드 
____규칙: 200(“OK”)는 일반적인 요청 성공을 나타내는 데 사용해야 한다 
____규칙: 200(“OK”)는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다 
____규칙: 201(“Created”)는 성공적으로 리소스를 생성했을 때 사용해야 한다 
____규칙: 202(“Accepted”)는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다 
____규칙: 204(“No Content”)는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다 
____규칙: 301(“Moved Permanently”)는 리소스를 이동시켰을 때 사용한다 
____규칙: 302(“Found”)는 사용하지 않는다 
____규칙: 303(“See Other”)은 다른 URI를 참조하라고 알려줄 때 사용한다 
____규칙: 304(“Not Modified”)는 대역폭을 절약할 때 사용한다 
____규칙: 307(“Temporary Redirect”)은 클라이언트가 다른 URI로 요청을 다시 보내게 할 때 사용해야 한다 
____규칙: 400(“Bad Request”)은 일반적인 요청 실패에 사용해야 한다 
____규칙: 401(“Unauthorized”)은 클라이언트 인증에 문제가 있을 때 사용해야 한다 
____규칙: 403(“Forbidden”)은 인증 상태에 상관없이 액세스를 금지할 때 사용해야 한다 
____규칙: 404(“Not Found”)는 요청 URI에 해당하는 리소스가 없을 때 사용해야 한다 
____규칙: 405(“Method Not Allowed”)는 HTTP 메서드가 지원되지 않을 때 사용해야 한다 
____규칙: 406(”Not Acceptable”)은 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야 한다
____규칙: 409(“Conflict”)는 리소스 상태에 위반되는 행위를 했을 때 사용해야 한다 
____규칙: 412(“Precondition Failed”)는 조건부 연산을 지원할 때 사용한다 
____규칙: 415(“Unsupported Media Type”)은 요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야 한다 
____규칙: 500(“Internal Server Error”)는 API가 잘못 작동할 때 사용해야 한다 
__04 정리 

4장. 메타데이터 디자인 
__01 HTTP 헤더 
____규칙: Content-Type을 사용해야 한다 
____규칙: Content-Length를 사용해야 한다 
____규칙: Last-Modified는 응답에 사용해야 한다 
____규칙: ETag는 응답에 사용해야 한다 
____규칙: 스토어는 조건부 PUT 요청을 지원해야 한다 
____규칙: Location은 새로 생성된 리소스의 URI를 나타내는 데 사용해야 한다 
____규칙: Cache-Control, Expires, Date 응답 헤더는 캐시 사용을 권장하는 데 사용해야 한다 
____규칙: Cache-Control, Expires, Pragma 응답 헤더는 캐시 사용을 중지하는 데 사용해야 한다 
____규칙: 캐시 기능은 사용해야 한다 
____규칙: 만기 캐싱 헤더는 200(“OK”) 응답에 사용해야 한다 
____규칙: 만기 캐싱 헤더는 ‘3xx’ 와 ‘4xx’ 응답에 선택적으로 사용될 수 있다 
____규칙: 커스텀 HTTP 헤더는 HTTP 메서드의 행동을 바꾸는 데 사용해서는 안 된다 
__02 미디어 타입 
____미디어 타입 문법 
____등록된 미디어 타입 
____벤더 고유 미디어 타입 
__03 미디어 타입 설계 
____규칙: 애플리케이션 고유 미디어 타입을 사용해야 한다 
____규칙: 리소스의 표현이 여러 가지 가능할 경우 미디어 타입 협상을 지원해야 한다 
____규칙: query 변수를 사용한 미디어 타입 선택을 지원할 수 있다 
__04 정리 

5장. 표현 디자인 
__01 메시지 바디 포맷 
____규칙: JSON 리소스 표현을 지원해야 한다 
____규칙: JSON은 문법에 잘 맞아야 한다 
____규칙: XML과 다른 표현 형식은 선택적으로 지원할 수 있다 
____규칙: 추가 봉투는 없어야 한다 
__02 하이퍼미디어 표현 
____규칙: 링크는 일관된 형태로 나타내야 한다 
____규칙: 링크 관계를 표현할 때에는 일관된 형태를 사용해야 한다 
____규칙: 링크를 표현할 때는 일관된 형태를 사용해야 한다 
____규칙: 응답 메시지 바디 표현에 셀프 링크를 포함해야 한다 
____규칙: 진입 API URI 수를 최소화하라 
____규칙: 리소스의 상태에 따라 가능한 액션을 표현하기 위해서 링크를 사용해야 한다 
__03 미디어 타입 표현 
____규칙: 미디어 타입 format은 일관성 있는 폼을 사용해야 한다 
____규칙: 미디어 타입 스키마를 표현할 때는 일관성 있는 형식을 사용해야 한다 
__04 오류 표현 
____규칙: 오류는 일관성 있게 표현한다 
____규칙: 오류 응답은 일관성 있게 표현한다 
____규칙: 일반적인 오류 상황에서는 일관성 있는 오류 타입을 사용해야 한다 
__05 정리 

6장. 클라이언트 영역 
__01 개요 
__02 버전을 정의하는 방법 
____규칙: 새로운 개념을 도입하려면 새로운 URI를 사용해야 한다 
____규칙: 표현 형태의 버전을 관리하기 위해서는 스키마를 사용해야 한다 
____규칙: 엔티티 태그는 표현 상태 버전을 관리하기 위해 사용한다 
__03 보안
____규칙: 리소스 보호를 위해 OAuth를 사용할 수 있다 
____규칙: 리소스 보호를 위해 API 관리 솔루션을 사용할 수 있다 
__04 응답 표현 조합 
____규칙: URI의 쿼리 부분은 부분 응답을 지원할 때 사용해야 한다 
____규칙: URI 쿼리 부분은 연결된 리소스를 포함할 때 사용해야 한다
__05 하이퍼미디어 처리 
__06 자바스크립트 클라이언트 
____규칙: 자바스크립트에서 여러 웹 사이트에 읽기 접근이 가능하도록 JSONP를 지원해야 한다 
____규칙: 자바스크립트에서 여러 웹 사이트에 읽기/쓰기 접근이 가능하도록 CORS를 지원해야 한다 
__07 정리 

7장. 마지막 생각 
__01 최고의 수준 
__02 일관된 구현 
____원리: REST API 설계는 필요 이상으로 다르다 
____원리: REST API는 구현되는 것이 아니라 설계되어야 한다 
____원리: 프로그래머와 그들 조직의 일관성은 도움이 된다
____원리: REST API는 GUI 도구로 만들어진다 
__03 정리 

Appendix 
__나의 첫 번째 REST API