REST API 디자인 규칙
한빛 미디어의 e-book "일관성 있는 웹 서비스 인터페이스 설계를 위한 REST API 디자인 규칙" 의 목차에서 추려낸 REST API 디자인 규칙.
지켜오던것도 있고 원칙은 알고있었지만 이런저런 이유로 현실에는 적용하기 어려운 부분도 있지만 이런 원칙을 상기하면서 개발하면 좀 더 일관성있는 API를 구성할 수 있을듯 하다.
목차만으로도 많은 의미가 전달되기에 여기 발췌해둔다.
02장. URI 식별자 설계
02 URI 형태
규칙: 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
규칙: URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
규칙: 하이픈(-)은 URI 가독성을 높이는 데 사용한다.
규칙: 밑줄( _ )은 URI에 사용하지 않는다.
규칙: URI 경로에는 소문자가 적합하다.
규칙: 파일 확장자는 URI에 포함시키지 않는다.
03 URI 권한 설계
규칙: API에 있어서 서브 도메인은 일관성 있게 사용해야 한다.
규칙: 클라이언트 개발자 포탈 서브 도메인 이름은 일관성 있게 만들어야 한다.
04 리소스 모델링
05 리소스 원형
도큐먼트.
컬렉션.
스토어.
컨트롤러.
06 URI 경로 디자인
규칙: 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
규칙: 컬렉션 이름으로는 복수 명사를 사용해야 한다.
규칙: 스토어 이름으로는 복수 명사를 사용해야 한다.
규칙: 컨트롤러 이름으로는 동사나 동사구를 사용해야 한다.
규칙: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
규칙: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.
07 URI Query 디자인
규칙: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
규칙: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 한다.
3장. HTTP를 이용한 인터랙션 설계
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가 잘못 작동할 때 사용해야 한다.
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 변수를 사용한 미디어 타입 선택을 지원할 수 있다.
5장. 표현 디자인
01 메시지 바디 포맷
규칙: JSON 리소스 표현을 지원해야 한다.
규칙: JSON은 문법에 잘 맞아야 한다.
규칙: XML과 다른 표현 형식은 선택적으로 지원할 수 있다.
규칙: 추가 봉투는 없어야 한다.
02 하이퍼미디어 표현
규칙: 링크는 일관된 형태로 나타내야 한다.
규칙: 링크 관계를 표현할 때에는 일관된 형태를 사용해야 한다.
규칙: 링크를 표현할 때는 일관된 형태를 사용해야 한다.
규칙: 응답 메시지 바디 표현에 셀프 링크를 포함해야 한다.
규칙: 진입 API URI 수를 최소화하라.
규칙: 리소스의 상태에 따라 가능한 액션을 표현하기 위해서 링크를 사용해야 한다.
03 미디어 타입 표현
규칙: 미디어 타입 format은 일관성 있는 폼을 사용해야 한다.
규칙: 미디어 타입 스키마를 표현할 때는 일관성 있는 형식을 사용해야 한다.
04 오류 표현
규칙: 오류는 일관성 있게 표현한다.
규칙: 오류 응답은 일관성 있게 표현한다.
규칙: 일반적인 오류 상황에서는 일관성 있는 오류 타입을 사용해야 한다.
6장. 클라이언트 영역
02 버전을 정의하는 방법
규칙: 새로운 개념을 도입하려면 새로운 URI를 사용해야 한다.
규칙: 표현 형태의 버전을 관리하기 위해서는 스키마를 사용해야 한다.
규칙: 엔티티 태그는 표현 상태 버전을 관리하기 위해 사용한다.
03 보안
규칙: 리소스 보호를 위해 OAuth를 사용할 수 있다.
규칙: 리소스 보호를 위해 API 관리 솔루션을 사용할 수 있다.
04 응답 표현 조합
규칙: URI의 쿼리 부분은 부분 응답을 지원할 때 사용해야 한다.
규칙: URI 쿼리 부분은 연결된 리소스를 포함할 때 사용해야 한다.
05 하이퍼미디어 처리
06 자바스크립트 클라이언트
규칙: 자바스크립트에서 여러 웹 사이트에 읽기 접근이 가능하도록 JSONP를 지원해야 한다.
규칙: 자바스크립트에서 여러 웹 사이트에 읽기/쓰기 접근이 가능하도록 CORS를 지원해야 한다.
