REST, REST API(RESTful API)

REST에 대한 대략적인 이해를 마쳤으니, 이번에는 REST API의 특징과 디자인하기 위한 방법들을 학습하고 정리하고자 한다.

REST API의 구성

REST API의 구성은 다음과 같다.

• 자원(RESOURCE) - URI
• 행위(Verb) - HTTP METHOD
• 표현(Representations)

잘 표현된 HTTP URI로 리소스를 정의히고 HTTP method로 리소스에 대한 행위를 정의한다. 리소스는 JSON, XML과 같은 여러 가지 언어로 표현할 수 있다.

REST API의 특징

이전에 학습한 내용을 토대로 간단히 정리하자면 REST는 'Representatinal State Transfer'의 약자로 하나의 URI는 하나의 고유한 리소스(Resource)를 대표하도록 설계된다는 개념에 전송방식을 결합해서 원하는 작업을 지정한다.
HTTP URI를 통해 제어할 자원(Resource)를 명시하고, HTTP Method(GET, POST, PUT, DELETE)을 통해 해당 자원을 제어하는 명령을 내리는 방식의 아키텍처이다.

REST API 디자인 가이드

REST API 설계 시 가장 중요한 항목은 2가지

• URI는 정보의 자원을 표현해야한다.
• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

URI는 정보의 자원을 표현해야한다.

GET /members/delete/1

위 예시처럼 delete와 같은 행위에 대한 표현이 들어가서는 안된다.

자원에 대한 행위는 HTTP Method로 표현

위 URI를 HTTP Method를 통해 수정한다면 아래와 같이 수정할 수 있다.

DELETE /members/1

HTTP METHOD

• POST
  POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
• GET
  GET을 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
• PUT
  PUT을 통해 해당 리소스를 수정한다.
• DELETE
  DELETE를 통해 리소스를 삭제한다.

자원에 대한 행위는 위 HTTP Method를 통해 정의해야한다.

URI 설계 시 주의할 점

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

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

3. 하이픈(-)은 URI 가독성을 높이는데 사용한다.

4. 언더바(_)은 URI에 사용하지 않는다.

5. 확장자가 포함된 파일 이름을 직접 포함시키지 않는다.

6. 특별한 경우를 제외하고 대문자 사용은 하지 않는다.(대소문자 구분을 하기 때문)

7. URI는 명사를 사용한다.

리소스 간의 관계를 표현하는 방법

/리소스명/리소스 ID/관계가 있는 다른 리소스명

ex)    GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

위와 같이 표현하되 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다. 예를 들어 사용자가 '좋아하는' 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있다.

GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

자원을 표현하는 Collection과 Document

여기서 Document는 단순히 문서 혹은 하나의 객체라고 이해하여도 되고, Collection은 문서들의 집합 혹은 객체들의 집합이라고 이해하면 된다.
두 가지 모두 리소스라고 표현할 수 있으며 URI에 표현된다.

http:// restapi.example.com/sports/soccer/players/13

위 URI에서 sports, players는 컬랙션, soccer, 13(13번 선수)을 의미하는 Document로 이루어지게 된다. 좀 더 직관적인 REST API를 위해서는 Collection 과 Document를 사용할 때 단수, 복수를 지켜준다면 좀 더 이해하기 쉬운 URI를 설계 할 수 있다.

HTTP 응답 상태 코드

응답 상태코드에 대해 간단하게 몇 가지만 정리해 보면 아래 표와 같다.

상태코드	설명
200	클라이언트 요청을 정상적으로 수행함
201	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨
301	클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드
400	클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
401	유저 인증상태와 관계없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
405	클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답코드
500	서버에 문제가 있을 경우 사용하는 응답 코드

Reference

https://spoqa.github.io/2012/02/27/rest-introduction.html
https://meetup.toast.com/posts/92