REST API

rest-api-01

현재의 서비스는 멀티 플랫폼을 지원하도록 개발되고 있다. 브라우저 뿐만 아니라 아이폰, 안드로이드의 어플리케이션들과의 통신에 대응해야한다. 때문에 각 플랫폼에 대응하는 서버를 새로 개발하지 않도록 범용적인 통신 디자인이 필요하다.

REST 아키텍쳐는 Hypermedia API의 기본을 충실히 이행하여 만들고자 하는 시스템 디자인의 기준을 명확히하고 범용성을 보장하게 해준다. REST의 기본 원칙을 잘 지킨 서비스 디자인은 “RESTful 하다.”라고 표현된다. 프로토콜에 맞춰 잘 디자인된 API는 설명을 간결하게 해주며 버전, 포맷 또는 언어같은 문제 상황을 해결하는데 도움이 된다.

REST 구성

REST는 리소스, 메서드, 메세지의 3가지 요소로 구성된다.

  • 리소스 : REST의 특징 중 하나로, URI를 통해 모든 자원을 표현한다.
  • 메서드 : 행위를 의미하며, HTTP Method (POST, GET, PUT, DELETE - CRUD 순)로 표현된다.
  • 메세지 : 행위를 위한 정보를 의미한다.

위 3가지 요소를 통해 HTTP 프로토콜을 의도에 맞게 디자인할 수 있다.

REST 규칙

RESTful한 API를 설계하기 위한 기본 규칙은 다음과 같다.

  • 리소스는 URI를 통해 정보의 자원을 표현한다.

  • 메서드는 행위를 의미하며 HTTP Method(GET, POST, PUT, DELETE)로 표현된다.

REST의 URI는 기본적으로 계층간 has 관계를 표현한다. 행위에 대한 표현은 HTTP Method로 대변하기 때문에 URI 자체에 행위에 대한 표현은 사용하지 않는다.

  • ex) GET : /users/{userid}/devices

자원은 Collection과 Element로 나눌 수 있다. 이름에서 알 수 있듯이 Collection은 여러개의 Element를 의미하며 URI에서 복수형으로 표현된다.

자원의 타입과 메서드의 종류에 따라 다음과 같이 표현된다.

Resource
GET
PUT
POST
DELETE
Collection URI
http://expamle.com/resources
컬렉션에 속한 자원들의 URI나 그 상세사항의 목록을 보여준다. 해당 컬렉션을 다른 컬렉션으로 전부 교체한다. 해당 컬렉션에 속하는 새로운 자원을 생성한다. 컬렉션을 삭제한다.
Element URI
http://expamle.com/resources/item
요청한 컬렉션 내 자원을 반환한다. 해당 자원을 수정한다. 잘 사용되지 않는다. 해당 컬렉션에 속하는 새로운 자원을 생성한다. 해당 컬렉션 내 자원을 삭제한다

REST 아키텍처에 적용되는 6가지 제한조건

  • 클라이언트/서버 구조를 갖는다.
  • 무상태Stateless : 각 요청 간 클라이언트의 콘텍스트가 서버에 저장되어서는 안된다.
  • 캐시Cacheable : www와 같이 클라이언트는 응답을 캐시할 수 있다.
  • 계층화Layered System : 클라이언트는 대상 서버에 직접 연결되었는지, 중간 서버에 연결되었는지 알 수 없다.
  • 인터페이스 일관성 : 아키텍처를 단순화하고, 작은 단위로 분리하여 서버와 클라이언트의 각 부분이 독립적으로 개선되도록 한다.
  • Code on Demand (optional) : 자바 애플릿이나 자바스크립트의 제공을 통에 클라이언트가 실행할 수 있는 로직을 전송하여 기능을 확장시킬 수 있다.

URI 설계시 주의할 점

  • 슬래시(/)로 계층 관계를 표현
  • URI 마지막 문자로 슬래시를 사용하지 않는다.
  • 하이픈(-) 으로 가독성을 높인다. : 긴 URI는 하이픈으로 구분
  • 밑줄(_)은 사용하지 않는다.
  • 경로는 소문자로.
  • URI에 파일 확장자는 포함하지 않는다.

HTTP Request 상태코드

200

클라이언트의 요청을 정상적으로 수행함

201

클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨 (POST를 통한 리소스 생성 작업 시)

301

클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드 (응답 시 Location header에 변경된 URI를 적어 줘야 합니다.)

400

클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드

401

클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 (로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)

403

유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 (403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에)

405

클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드

500

서버에 문제가 있을 경우 사용하는 응답 코드