REST API

1. REST API의 탄생

REST(Representational State Transfer)는 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었습니다.
로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다.

2. REST 구성

• 자원 (Resource) - URI
• 행위 (Verb) - HTTP METHOD
• 표현 (Representation)

3. REST 특징

1) Uniform (유니폼 인터페이스)
Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 의미함.

2) Stateless (무상태성)
REST는 무상태성 성격을 갖습니다. 다시 말해 작업을 위한 상태정보(세션 정보나 쿠키 정보)를 별도로 저장하고 관리하지 않습니다.
API 서버는 들어오는 요청만을 단순히 처리하면 됩니다.

때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해집니다.

3) Cacheable (캐시 가능)
REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하다는 점이다.

따라서 HTTP가 가진 캐싱 기능을 적용할 수 있다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능합니다.

4) Self-descriptiveness (자체 표현 구조)
REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다는 것입니다.

5) Client - Server 구조
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 됩니다.

6) 계층형 구조
REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다.

4. API란?

API(Application Programming Interface) : 한 프로그램에서 다른 프로그램으로 데이터를 주고받기 위한 방법

일단 API의 개념을 이해하기 위한 예시를 살펴보자.

ex-1) 식당

메뉴를 주문할 때 식당에서 손님에게 메뉴판을 준다 ⇒ 손님은 메뉴판에 있는 메뉴를 보고 뭘 먹을지 결정한다.

ex-2) 웹툰 보내주는 프로그램

웹툰볼 때 프로그램은 사용자에게 어떤 웹툰이 있는지 보여준다 ⇒ 사용자는 게시되어 있는 웹툰 중 하나를 골라 웹툰을 본다.

이렇듯, 식당에서는 식당과 손님이 음식을 주고받기 위한 방법으로 메뉴판을 제공하고
웹툰 프로그램에서는 웹툰서버와 손님이 웹툰을 주고받기 위한 방법으로 API를 제공한다.

여기서 얘기하는 방법은 코드를 통해 구현된다.

ex) 코드를 실행하면 DB에서 웹툰을 뽑아내서 보여주는 코드

db.collection('웹툰').findOne({_id: parseInt(요청.params.id) }, function(에러, 결과) { 
  console.log(결과); 
  res.render('detail.ejs', {data: 결과}); 
})

코드의 기능은 알겠지만 이걸 유저가 어떻게 사용할 수 있을까. 코드에 직접 접근하지 않는 이상 동작할 수는 없다.

그래서 다음과 같이 코드를 수정한다.

app.get('/detail/:id', function(req, res) {
  db.collection('웹툰').findOne({_id: parseInt(요청.params.id) }, function(에러, 결과) { 
    console.log(결과); 
    res.render('detail.ejs', {data: 결과}); 
  })

/detail/:id url로 GET 요청이 온다면... 위에서 정의한 코드를 실행하도록 했다.
이때, GET 요청을 통해 url로 접속하도록 한 부분이 바로 API이다.

즉, 사용자가 API를 요청하려면 GET, POST 요청 등과 URL, 파라미터를 이용해서 코드를 작성해줘야 한다.
(ex. (GET 요청) comic.naver.com/webtoon/detail?titleId=641253 ==> 외모지상주의 웹툰이 조회되도록 함)

• API가 가져야 할 내용 ==> 웹의 경우 REST API라는 원칙에 따라 작성하면 좋다.

1) 어떤 요청 방식을 사용할 지 ex. GET 요청

2) 무슨 자료를 요청할 지 ex. comic.naver.com/webtoon/detail

3) 추가 정보(파라미터) (?로 시작해서 &로 구분함) ex. ?titleId=641253&no=439

5. REST API 디자인 가이드

REST API 설계 시 가장 중요한 항목은 다음의 2가지로 요약할 수 있습니다. 이 두 가지는 꼭 기억하자

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

5-1. REST API 중심 규칙

1) URI는 정보의 자원을 표현해야 한다. (리소스 이름은 명사를 사용할 것)

2) 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.

GET /members/delete/1 - URI는 자원을 표현하는데 중점을 두어야 한다. delete와 같은 행위에 대한 표현이 들어가면 안된다.

==> 수정하면... DELETE /members/1 

• 회원정보를 가져오고 싶을 때

GET /members/show/1 (x)
GET /members/1        (o)

• 회원정보를 추가할 때

GET /members/insert/2 (x)  - GET 메서드는 리소스 생성에 맞지 않습니다.
POST /members/2       (o)

METHOD	역할
POST	POST를 통해 URI를 요청하면 리소스를 생성함
GET	GET을 통해 해당 리소스를 조회함
PUT	PUT을 통해 해당 리소스를 수정함
DELETE	DELETE를 통해 해당 리소스를 삭제함

위와 같이 URI는 자원을 표현하는데 집중 & HTTP METHOD는 행위를 표현하는데 집중하는 것이 REST API의 설계의 중심 규칙이다.
(물론, 이 상황이 항상 맞아떨어지지는 않아서 다양한 상황이 생긴다고 하는데 이에 대한 정리는 추후에)

5-2 URI 설계 시 주의점

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

    http://restapi.example.com/houses/apartments
    http://restapi.example.com/animals/mammals/whales

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

http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments  (O)

3) 하이픈(-)은 URI의 가독성을 높이는데 사용 & 밑줄(_)은 사용하지 않음

http://restapi.example.com/houses-blue-container/apartments  (O)
http://restapi.example.com/houses_blue_container/apartments  (X)

4) URI 경로에는 소문자가 적합 - RFC 3986에서 정의

5) 파일 확장자를 URI에 포함시키지 말 것

http://restapi.example.com/members/soccer/345/photo.jpg (X)

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다.
Accept header를 사용하도록 하자.

GET /members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

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

REST 리소스 간에는 연관 관계가 있을 수 있다. 이런 경우 다음과 같은 표현방법을 사용하자.

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

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

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

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

5-4 자원을 표현하는 Document과 Collection

• Document : 문서 또는 하나의 객체로 볼 수 있음
• Collection : 문서들의 집합, 객체들의 집합

이것들은 모두 리소스라고 표현할 수 있고 URI에 표현된다.

http://restapi.example.com/sports/soccer 
==> sports라는 컬렉션과 soccer라는 도큐먼트로 표현되어 있다고 볼 수 있음

http://restapi.example.com/sports/soccer/players/13
==> sports라는 컬렉션과 soccer라는 도큐먼트 & players라는 컬렉션과 13이라는 도큐먼트로 표현되어 있다고 볼 수 있음

좀 더 직관적인 REST API를 위해서 컬렉션은 복수 & 도큐먼트는 단수를 사용한다면 좀 더 이해하기 쉬운 URI를 설계할 수 있다.

6. HTTP 응답 상태 코드 - 공식 문서 모음

REST API는 리소스에 대한 응답도 잘 보내줘야 한다.
특히, 응답에 대한 정확한 상태코드만으로도 많은 정보를 전달할 수 있기 때문에 응답에 대한 상태코드 값을 명확히 반환하는 것이 중요하다.

• 2xx

  상태코드	내용
  200	client의 요청 정상 수행
  201	client의 리소스 생성 요청을 정상적으로 수행(POST를 통한 리소스 생성 작업 시)

• 4xx

  상태코드	내용
  400	client의 요청이 부적절한 경우
  401	인증되지 않은 client가 보호된 리소스를 요청한 경우
  	ex) 로그인하지 않은 유저가 로그인했을 때 요청 가능한 리소스를 요청한 경우
  403	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청한 경우
  	(403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 걸 의미하기 때문)
  404	client가 요청한 리소스를 찾을 수 없는 경우 (Not Found)
  405	client가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우

• 301, 5xx

  상태코드	내용
  301	client가 요청한 리소스의 URI가 변경된 경우
  	(응답 시 Location header에 변경된 URI를 적어 줘야 합니다.)
  500	서버에 문제가 있는 경우
  503	서버가 요청을 처리할 준비가 되지 않은 경우

출처

https://meetup.nhncloud.com/posts/92
코딩애플 API 영상