2013년 7월 28일

Restful API, URI 이름 설계

Restful API 이름 명명 간단 요약

URI 형태

  • 규칙1: 슬래시(/) 구분자는 계층 관계를 나타내는데 사용한다.
  • 규칙2: URI 마지막 문자로 슬래시를 포함하지 않는다.
  • 규칙3: 하이픈(-)은 URI 가독성을 높이는데 사용한다.
  • 규칙4: 밑줄(_)은 URI 경로에 사용하지 않는다.
  • 규칙5: URI 경로는 소문자가 적합하다.
  • 규칙6: 파일 확장자는 URI에 포함시키지 않는다.


URI 경로디자인

  • 규칙1: 도큐먼트 이름으로는 단수명사를 사용해야한다.
  • 규칙2: 컬렉션 이름으로는 복수명사를 사용해야한다.
  • 규칙3: 스토어 이름으로는 복수명사를 사용해야한다.
  • 규칙4: 컨트롤러 이름으로는 동사나 동사구를 사용해야한다.
  • 규칙5: 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.
  • 규칙6: CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.


URI Query 디자인

  • 규칙1: URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
  • 규칙2: URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는데 사용해야한다.



HTTP를 이용한 인터렉션 설계 - 요청 메서드

  • 규칙1: GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는 안된다.
  • 규칙2: GET 메서더는 리소스의 상태 표현을 얻는데 사용해야한다.
  • 규칙3: 응답 헤더를 가져올 때는 반드시 HEAD 메서드를 사용해야한다.
  • 규칙4: PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는데 사용해야한다.
  • 규칙5: PUT 메서드는 변경 가능한 리소스를 갱신하는데 사용해야한다.
  • 규칙6: POST 메서드는 컬렉션에 새로운 리소스를 만드는데 사용해야한다.
  • 규칙7: POST 메서드는 컨트롤러를 실행하는데 사용해야한다.
  • 규칙8: DELETE 메서드는 그 부모에서 리소스를 삭제하는데 사용해야한다.
  • 규칙8: OPTIONS 메서드는 리소스의 사용 가능한 인터렉션을 기술한 메타데이터를 가져오는데 사용해야한다.


HTTP를 이용한 인터렉션 설계 - 응답상태코드

  • 규칙1: 200("OK")는 일반적인 요청 성공을 나타내는데 사용해야한다.
  • 규칙2: 200는 응답 바디에 에러를 전송하는데 사용해서는 안된다.
  • 규칙3: 201("created")는 성공적으로 리소스를 생성했을 때 사용해야한다.
  • 규칙4: 202("accepted")는 비동기 처리가 성공적으로 시작되었을음을 알릴 때 사용해야한다.
  • 규칙5: 204("No Content")는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다.
  • 규칙6: 301("Moved Permanently")는 리소스를 이동시켰을 때 사용한다.
  • 규칙7: 302("Found")는 사용하지 않는다.
  • 규칙8: 303("See Other")는 다른 URI를 참조하라고 알려줄 때 사용한다.
  • 규칙9: 304("Not Modified")는 대역폭을 절약할 때 사용한다.
  • 규칙10: 307("Temporary Redirect")은 클라이언트가 다른 URI로 요청을 다시 보내게할 때 사용해야한다.
  • 규칙11: 400("Bad Request")는 일반적인 요청 실패에 사용해야한다.
  • 규칙12: 401("Unauthorized")는 클라이언트 인증에 문제가 있을 때 사용해야한다.
  • 규칙13: 404("Not Found")는 요청 URI에 해당하는 리소스가 없을 때 사용해야한다.
  • 규칙14: 405("Method Not Allowed")는 HTTP 메서드가 지원되지 않을 때 사용해야한다.
  • 규칙15: 406("Not Acceptable")는 요청된 리소스 미디어 타입을 제공하지 못할 때 사용해야한다. 
  • 규칙16: 409("Conflict")는 리소스 상태에 위반되는 행위를 했을 때 사용해야한다.
  • 규칙17: 412("Unsupported Media Type")는 요청의 페이로드에 있는 미디어 타입이 처리되지 못했을 때 사용해야한다.
  • 규칙18: 500("Internal Server Error")는 API가 잘못 작동할 때 사용해야한다.


메타데이터 디자인 - HTTP 헤더

  • 규칙1: Content-Type, Content-Length, Last-Modified, ETag는 응답에 사용해야한다.
  • 규칙2: 스토어는 조건부 PUT 요청을 지원해야한다.
  • 규칙3: Location는 새로 생성된 리소스의 URI를 나타내는데 사용해야한다.
  • 규칙4: Cache-Control, Expires, Date 응답헤더는 캐쉬 사용을 권장하는데 사용해야한다.
  • 규칙5: Cache-Control, Expires, Pragma 응답 헤더는 캐쉬 사용을 중지하는데 사용해야한다.
  • 규칙6: 캐쉬 기능을 사용해야한다.
  • 규칙7: 만기 캐슁 헤더는 200("OK") 응답에 사용해야한다.
  • 규칙8: 만기 캐슁 헤더는 '3XX', '4XX' 응답에 선택적으로 사용될 수 있다.
  • 규칙9: 커스텀 헤더는 HTTP 메서드의 행동을 바꾸는데 사용해서는 안된다.


메타데이터 디자인 - 미디어 타입 설계

  • 규칙1: 어플리케이션 고유 미디어 타입을 사용해야한다.
  • 규칙2: 리소스의 표현이 여러가지 가능할 경우 미디어 타입 협상을 지원해야한다.
  • 규칙3: query 변수를 사용한 미디어 타입 선택을 지원할 수 있다.


원문 출처:
REST API Design Rulebook
Designing Consistent RESTful Web Service Interfaces
Publisher: O'Reilly Media
Released: October 2011

번역 출처: 권원상님, 김관래님 번역



댓글 없음:

댓글 쓰기