[가이드
내용]
l URI 경로 세그먼트는 언제 복수로 써야 하는가?
l 어떤 메서드를
사용해야 하는가?
l CRUD 가 아닌 연산을 어떻게 URL에 맵핑하는가?
[RESTful
리소스 원형 이해]
l 컬렉션 리소스 : 서버에서 관리하는
디렉터리를 리소스로 표현하기 위해 사용되는 모델.(ex: https://api.com/users
)
l 도큐먼트 리소스 : 객체의 인스턴스
또는 데이터베이스 테이블의 특정 레코드와 유사한 단수 개념 모델.(ex: https://api.com/users/155 )
l 스토어 리소스 : 클라이언트에
의해서 관리될 수 있는 리소스 저장소 모델. (ex: https://api.com/users/155/devices
)
l 컨트롤러 리소스 : 특정 동작을
실행하도록 구현한 함수 개념 모델. (ex: https://api.com/users/155/devices/775/resend
)
[설계
규칙]
l URI 형태(RFC 3986 정의 http://www.rfc-editor.org/rfc/rfc3986.txt )
n 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.
u / 는 경로내에서 리소스 간의 계층 관계를 나타내는 데 사용한다.
u ex) /shapes/polygons/quadrilaterals/squares
n URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
u URI 에 포함된 모든 문자는 리소스의 유일한 식별자임으로 엄밀히 말하면 서로 다른 리소스로의 맵핑이다.
n 하이픈(-)은 URI 가독성을 높이는 데 사용한다.
n 밑줄( _ )은 URI에 사용하지 않는다.(유행에
뒤쳐진 듯 합니다.)
n URI 경로에는 소문자가 적합하다.
u RFC 3986 에서 URI 스키마와 호스트를 제외하고는 대소문자를
구별한다.
n 파일 확장자는 URI에 포함시키지 않는다.
u .파일 포맷 타입대신 Content-Type 헤더로 결정한다.
l URI 경로 디자인
n 도큐먼트
이름으로는 단수 명사를 사용해야 한다.
u 단수 명사나
명사구를 포함하는 경로 부분으로 이름을 짓는다.
u Ex) /teams/busan/players/kimnamil
n 컬렉션 이름으로는
복수 명사를 사용해야 한다.
u 복수 명사나
명사구를 포함하는 경로로 이름을 지어야 한다.
u Ex) /teams/busan/players
n 스토어 이름으로는
복수 명사를 사용해야 한다.
u 복수 명사나
명사구를 포함하는 경로로 이름을 지어야 한다.
u Ex) /artists/kimkyungho/playlists
n 컨트롤러
이름으로는 동사나 동사구를 사용해야 한다.
u 프로그램에
사용하는 함수처럼 동작을 포함하는 이름으로 지어야 한다.
u Ex) /students/234/register
u Ex) /dbs/reindex
n 경로 부분
중 변하는 부분은 유일한 값으로 대체한다.
u Ex) /teams/{team-key}/players
n CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.
u Ex) /deleteUser
u Ex) /updateUser
l 요청 메서드
n GET 메서드나 POST 메서드를 사용하여 다른 요청 메서드를 처리해서는
안 된다.
n GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다.
n 응답 헤더를
가져올 때는 반드시 HEAD 메서드를 사용해야 한다.
n PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다.
n PUT 메서드는 변경 가능한 리소스를 갱신하는 데 사용해야 한다.
n POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다.
n POST 메서드는 컨트롤러를 실행하는 데 사용해야 한다.
n DELETE 메서드는 그 부모에서 리소스를 삭제하는 데 사용해야 한다.
n OPTIONS 메서드는 리소스의 사용 가능한 인터랙션을 기술한 메타데이터를 가져오는 데 사용해야 한다.
l URI 권한 설계
n API에 있어서 서브 도메인은 일관성 있게 사용해야 한다.
u API 최상위 도메인과 1차 서브 도메인 이름으로 서비스 제공자를 식별해야
한다.
u ex) http://api.socceer.restapi.org
n 클라이언트
개발자 포탈 서브 도메인 이름은 일관성 있게 만들어야 한다.
u REST API 를 제공하는 서비스업체들의 개발자 포털은 관습적으로 developer
를 서브도메인으로 사용한다.
l URI Query 디자인
n URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다.
n URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 한다.
참고 문헌 :
- O’reilly REST API Design
Rulebook(Mark Masse)
- http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/
- https://api.apigee.com
