URI 형태
RFC 3986 에 정의된 일반적인 URI 문법
URI =
scheme :// authority / path [? query] [# fragment ]슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다
- 포워드 슬래시(/)는 경로(path) 내에서 리소스 간의 계층 관계를 나타내는 데 사용
- http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
URI 마지막 문자로 슬래시(/)를 포함하지 않는다
- URI 경로 마지막에 있는 슬래시는 아무런 의미가 없지만, 혼란을 초래할 수 있음
- URI가 다르면 리소스가 달라야 하는데, 아래 두 개의 URL을 같게 보는 것은 엄격하게는 좋지 않음
- http://api.canvas.restapi.org/shapes/
- http://api.canvas.restapi.org/shapes
하이픈(-)은 URI 가독성을 높이는 데 사용한다
URI에서는 문장 내 공백을 하이픈으로 바꿀 수 있다
밑줄(_)은 URI에 사용하지 않는다
밑줄은 보기 어렵거나 밑줄 때문에 문자가 완전히 가려지기도 함
URI 경로에는 소문자가 적합하다
RFC 3986은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정
- 아래 1과 2는 같은 것으로 간주하지만, 3은 1,2와는 다른 URI임
- http://api.example.restapi.org/my-folder/my-doc
- HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc
- http://api.example.restapi.org/My-Folder/my-doc
파일 확장자는 URI에 포함시키지 않는다
REST API 에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함하지 않아도 됨. 대신 이 확장자는 미디어 타입에 의존(Content-Type 헤더)
URI 권한 설계
권한 : URI 구성요소로, URI의 나머지 부분을 관할하는 네임스페이스를 식별하는 데 사용됨
API에 있어서 서브 도메인은 일관성 있게 사용해야 함
API 최상위 도메인(예,
soccer.restapi.org)과 1차 서브 도메인 이름(api.soccer.restapi.org)으로 서비스 제공자를 식별해야 함클라이언트 개발자 포탈 서브 도메인 이름은 일관성 있게 만들어야 한다
보통 REST API는 개발자 포탈(Developer Portal)이라는 개발자들을 위한 웹 사이트를 지원한다. 이 포탈은 웹 사이트의 문서, 포럼, 포탈 내에서 직접 제공하는 안전한 API 접근키를 이용하여 새로운 클라이언트를 만드는 데 도움을 준다. 아래와 같은 url 형태로 개발자 포탈 제공
http://developer.soccer.restapi.org리소스 모델링
- URI 경로는 REST API의 리소스 모델을 다루는데, 포워드 슬래시로 경로 구문을 나눔
- 리소스 모델링은 API의 주요 개념을 확실하게 잡는 훈련과도 같음
- 이 과정은 마치 RDB 스키마를 정의하기 위한 데이터 모델링이나, 객체 지향 시스템에서의 클래스 모델링과 유사함
- URI 경로 설계에 들어가기 전, REST API의 리소스 모델에 대해 생각해 보는 것이 도움될 것임
리소스 원형 (Resource archetypes)
API 리소스를 모델링할 때, 기본적인 리소스 원형 몇 개를 가지고 시작할 수 있음
리소스 모델로 명확하고 정확하게 클라이언트와 통신하려면, REST API는 리소스 원형 중에서 리소스 하나로만 설계해야 한다. 일관성을 위해 리소스 원형 하나 이상을 이용하여 리소스를 설계하지 않도록 주의를 기울여야 한다. 대신, 링크를 통해 계층적으로 연관될 수 있는 분리된 리소스 설계를 고민해야 함
도큐먼트
- 객체 인스턴스나 데이터베이스 레코드와 유사한 단일 개념
- 일반적으로 도큐먼트의 상태 표현은
값을 가진 필드와다른 관련 리소스와의 링크둘 다를 가지게 됨 - 기본적인 필드와 링크 기반 구조로 인해, 도큐먼트 타입은 다른 리소스 원형들의 기반 원형이 됨
- 도큐먼트 리소스 예시
- http://api.soccer.restapi.org/leagues/seattle
- http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet
- http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/mike
컬렉션
- 컬렉션 리소스는
서버에서 관리하는 디렉터리라는 리소스
- 컬렉션 리소스 예시
- http://api.soccer.restapi.org/leagues
- http://api.soccer.restapi.org/leagues/seattle/teams
- http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players
스토어
클라이언트에서 관리하는 리소스 저장소. 스토어 리소스는 API 클라이언트가 리소스를 넣거나 빼는 것, 지우는 것에 관여함
- 스토어 스스로 새로운 리소스를 생성하지 못하기 때문에, 새로운 URI를 만들지는 못함
- 다음은 클라이언트 프로그램에서 id 가 1234인 사용자를 보여주고, 가상의 Soccer REST API를 사용하여 favorites라는 스토어에 alonso라는 도큐먼트 리소스를 넣는 예임
- PUT /users/1234/favorites/alonso
컨트롤러
- 컨트롤러 리소스는 절차적인 개념을 모델화한 것
- 컨트롤러 리소스는 실행 가능한 함수와 같아서 파라미터(입력 값)와 반환 값(출력 값)이 있다.
- REST API는 CRUD라고 알려진 표준적인 메서드와는 논리적으로 매핑되지 않는 애플리케이션 고유의 행동을 컨트롤러 리소스의 도움을 받아 수행함
- 일반적으로 컨트롤러 이름은 URI 경로의 제일 마지막 부분에 표시되며, 계층적으로 뒤따르는 자식 리소스는 없음
- 클라이언트가 사용자에게 경고를 재전송하게 하는 컨트롤러 리소스
PUT/alerts/245743/resend
URI 경로 디자인
도큐먼트 이름으로는 단수 명사를 사용해야 한다
한 명의 선수 도큐먼트를 나타내는 URI → 단수형태
http://api.soccer.rest.api/leagues/seattle/teams/trebuchet/players/claudio
컬렉션 이름으로는 복수 명사를 사용해야 한다
컬렉션을 식별하는 URI는 복수 명사나 복수 명사구를 나타내는 명사로 경로 이름을 지어야 함
컬렉션 이름은 균일하게 포함되도록 선택해야 함
선수 도큐먼트의 컬렉션 URI : http://api.soccer.rest.api/leagues/seattle/teams/trebuchet/players
스토어 이름으로는 복수 명사를 사용해야 한다
음악 플레이리스트 스토어의 URI는 다음과 같은 복수 명사 형태
http://api.music.restapi.org/artists/mikemassedotcom/playlists
컨트롤러 이름으로는 동사나 동사구를 사용해야 한다
프로그램에 사용하는 함수처럼, 컨트롤 리소스를 나타내는 URI는 동작을 포함하는 이름으로 지어야 한다.
예시
- http://api.college.restapi.org/students/morgan/register
- http://api.example.restapi.org/lists/4324/dedupe
- http://api.ognom.restapi.org/dbs/reindex
- http://api.build.restapi.org/qa/nightly/runTestSuite
경로 부분 중 변하는 부분은 유일한 값으로 대체한다
URI를 유일한 ID로 사용해야만 기존 클라이언트에 영향을 미치지 않고, REST API의 백엔드 시스템을 개선할 수 있음
CRUD 기능을 나타내는 것은 URI에 사용하지 않는다 (컨트롤러 내용과는 좀 다름)
URI는 리소스를 식별하는 데만 사용해야 하고,
HTTP 리퀘스트 메서드를 CRUD 기능을 수행하는 것을 의미할 때 사용
URI Query 디자인
URI 쿼리 부분으로 컬렉션이나 스토어를 필터링할 수 있다
GET /users → 응답 메시지의 상태 표현은 컬렉션에 있는 모든 사용자의 리스트다
GET /users?role=admin → 응답 메시지의 상태 표현은 컬렉션에 있는 사용자 중 ‘role’의 값이 admin인 사용자의 리스트
URI 쿼리는 컬렉션이나 스토어의 결과를 페이지로 구분하여 나타내는 데 사용해야 함
GET /users?pageSize=25&pageStartIndex=50 (50페이지부터 최대 75페이지까지만)- URI 쿼리로 클라이언트의 페이지나 필터링의 요구사항에 대응할 수 없다면, 컬렉션이나 스토어의 파트너가 될 수 있는 특별한 컨트롤러를 생각해봐야 함
- 예를 들어, 다음 컨트롤러는 URI 의 쿼리 파트 대신 리퀘스트의 바디 부분에 좀 더 복잡한 입력을 받을 수 있음 ⇒
POST/users/search - 이 디자인으로 맞춤 범위 형태나 특별한 소팅 순서 등이 클라이언트 리퀘스트 메시지 바디에 쉽게 기술될 수 있음