Rest api

REST란

REST's purpose

장단점

uri 식별자 설계

uri 형태

슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다

포워드 슬래시(/)는 경로path 내에서 리소스 간의 계층 관계를 나타내는 데 사용한다. 예를 들면 다음과 같다.

http://api.canvas.restapi.org/shapes/polygons/squares

URI 마지막 문자로 슬래시(/)를 포함하지 않는다

http://api.canvas.restapi.org/shapes/      (x)

http://api.canvas.restapi.org/shapes        (o)

 규칙을 엄격하게 적용하지 않은 API들은 클라이언트가 보낸 URI를 마지막에 슬래시(/)가 없는 URI로 리다이렉트하기도 한다. 

 즉, 클라이언트에서 URI 맨 뒤에 슬래시(/)를 붙이더라도 오류로 처리하지 않고 슬래시(/)가 없는 URI로 전용한다

URI 경로에는 소문자가 적합하다

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 포맷 스펙(RFC 3986)에서 ①과 같은 것으로 간주한다.

③은 ①, ②와는 다른 URI다. 대소문자를 섞어 사용하게 되면 때로 혼란을 일으킬 수 있다.

    파일 확장자는 URI에 포함시키지 않는다

http://api.college.restapi.org/students/transcripts/2005/fall.json ➊

http://api.college.restapi.org/students/transcripts/2005/fall ➋

① 파일 확장자를 포맷을 나타내는 용도로 사용해서는 안 된다.

② REST API 클라이언트에서 권장하는 방법은 HTTP에서 제공하는 포맷 선택 메 커니즘을 이용하는 것이다. 

 API에 있어서 서브 도메인은 일관성 있게 사용해야 한다

API 최상위 도메인과 1차 서브 도메인 이름(예, soccer.restapi.org)으로 서비스 제공자를 식별해야 한다.  API의 전체 도메인 이름에 api라는 서브 도메인을 다음과 같이 붙여야 한다.

 http://api.soccer.restapi.org

도큐먼트 이름으로는 단수 명사를 사용해야 한다

도큐먼트 리소스를 나타내는 URI는 단수 명사나 명사구를 포함하는 경로 부분으로 이름을 짓는다. 예를 들면, 한 명의 선수 도큐먼트를 나타내는 URI는 단수 형태가 되어야 한다

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio

* 도큐먼트 : 이 책에서 도큐먼트라 함은 객체 인스턴스나 데이터베이스 레코드와 유사한 단일 개념이다

컬렉션 이름으로는 복수 명사를 사용해야 한다

컬렉션을 식별하는 URI는 복수 명사나 복수 명사구를 나타내는 명사로 경로의 이름을 지어야 한다. 그리고 컬렉션 이름은 균일하게 포함되도록 선택해야 한다. 예를 들어, 선수 도큐먼트의 컬렉션 URI는 포함된 리소스의 복수 명사 형태로 나타낸다.

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players

경로 부분 중 변하는 부분은 유일한 값으로 대체한다

http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/21 ➊

http://api.soccer.restapi.org/games/3fd65a60-cb8b-11e0-9572-0800200c9a66 ➋

① 21이라는 값이 playerId를 대체하고 있다.

② UUID 값이 gameId를 대체하고 있다.

REST API의 클라이언트에서는 URI가 하나의 유의미한 리소스 식별자임을 고려해야 한다. 백엔드 시스템의 식별자(이를 테면, 데이터베이스의 ID와 같은)가 URI 경로에 표시될 수 있지만, 이는 클라이언트 코드 입장에서는 별로 의미가 없다. URI를 유일한 ID로 사용해야만 기존 클라이언트에 영향을 미치지 않고, REST API의 백엔드 시스템을 개선할 수 있다. 

CRUD 기능을 나타내는 것은 URI에 사용하지 않는다

DELETE /users/1234  ( O )

GET /deleteUser?id=1234  ( X )

GET /deleteUser/1234  ( X )

DELETE /deleteUser/1234  ( X )

POST /users/1234/delete  ( X )

CRUD 기능을 나타내는 것은 URI에 사용하지 않는다

DELETE /users/1234  ( O )

GET /deleteUser?id=1234  ( X )

GET /deleteUser/1234  ( X )

DELETE /deleteUser/1234  ( X )

POST /users/1234/delete  ( X )

GET 메서드는 리소스의 상태 표현을 얻는 데 사용해야 한다

웹은 구조상 GET 메서드의 특성에 많이 의존한다. 클라이언트에서 GET 요청을 반복해도 문제가 없어야 하며, 캐시는 리소스를 제공하는 원래 서버와 통신하지 않고도 캐시된 내용을 제공할 수 있어야 한다. 

PUT 메서드는 리소스를 삽입하거나 저장된 리소스를 갱신하는 데 사용해야 한다

PUT 메서드는 클라이언트가 기술한 URI로 스토어에 새로운 리소스를 추가하는 데 사용한다. 이미 스토어에 저장된 리소스를 갱신하거나 다른 것으로 대체하는 데도 PUT 메서드를 사용한다.

POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다

POST 메서드는 컬렉션에 새로운 리소스를 만드는 데 사용해야 한다

200(“OK”)는 일반적인 요청 성공을 나타내는 데 사용해야 한다

200(“OK”)는 응답 바디에 에러를 전송하는 데 사용해서는 안 된다

201(“Created”)는 성공적으로 리소스를 생성했을 때 사용해야 한다

202(“Accepted”)는 비동기 처리가 성공적으로 시작되었음을 알릴 때 사용해야 한다

204(“No Content”)는 응답 바디에 의도적으로 아무것도 포함하지 않을 때 사용한다

301(“Moved Permanently”)는 리소스를 이동시켰을 때 사용한다

303(“See Other”)은 다른 URI를 참조하라고 알려줄 때 사용한다

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가 잘못 작동할 때 사용해야 한다