[Web] REST API

REST

REST는 Representational State Transfer의 약자이며, HTTP 기반에서 URI로 resource를 나타내고, Method로 operation을 나타내는 것을 말한다. 그리고 이러한 형식을 따를 때 해당 API가 Restful하다고 말한다.

설계 방식

REST API는 아래와 같은 Method로 CRUD를 표현한다.

Operation	Method	Example
Create	POST	/customers
Read	GET	/customers/{id}
Update	PUT	/customers/{id}
Delete	DELETE	/customers/{id}

설계 시 주의해야할 점은 아래와 같다.

1. 동작이나 행위는 Method를 통해 표현하고 URI에 나타내지 않는다.
   • /get/customers (X)
   • /customers/show (X)

2. 소문자로 표현하며 언더바(_) 보다는 하이픈(-)을 사용한다.

3. URI의 마지막에는 슬래시(/)가 포함되서는 안된다.

4. 계층 구조는 슬래시를 통해서 나타낸다.
   • /customers/{id}/device (해당 id를 가지는 고객이 가진 디바이스 정보)

장점

1. Restful하다는 것은 별도의 도큐먼트를 보지 않아도 URI, Method 만으로 어떠한 동작을하는지 예측할 수 있다.
2. REST API는 Stateless이다. Session이나 Cookie 같은 클라이언트에 대한 context를 유지하지 않기 때문에 구현이 단순해진다.

단점

1. 단순 CRUD만을 나타내는 Method로 인해, 특별하거나 상세한 동작을 구현하는데 있어서는 제약이 존재할 수 있다.
2. REST는 공식적인 표준이 존재하지 않는다.

PUT과 PATCH

아직은 잘 지원하지 않는 부분이 많지만 업데이트에 해당하는 PUT과 유사한 PATCH가 있다.

• PUT : 리소스 전체에 대한 업데이트
• PATCH : 리소스 부분에 대한 업데이트

예를 들어 다음과 같은 리소스가 존재한다고 하자.

seq	id	email	phone_number
1	stalker	stalker5217@gmail.com	010-1234-5678

업데이트 구문은 다음과 같다.

PUT /customers/1  
{
  id: "stalker",
  email: "stalker5217@gmail.com",
  phone_number: "010-1111-1111"
}

seq	id	email	phone_number
1	stalker	stalker5217@gmail.com	010-1111-1111

이처럼 PUT은 항상 전체 리소스에 대한 전송을 전제로 한다. 그렇기에 필드에 대한 값이 누락된다면 null처리가 된다.

PUT /customers/1  
{
  id: "stalker",
  phone_number: "010-1111-1111"
}

seq	id	email	phone_number
1	stalker	null	010-1234-5678

PUT은 리소스의 교체 성격이 강하다. 그리고 리소스의 부분 수정을 담당하는 것이 PATCH이다.

PATCH /customers/1  
{
  id: "stalker",
  phone_number: "010-1111-1111"
}

seq	id	email	phone_number
1	stalker	stalker5217@gmail.com	010-1111-1111

HTTP 상태 코드

일반적으로 API 구성 시 많이 나타나는 코드에 대한 정리이다.

분류	설명	응답 코드	설명
2XX	정상 응답	200 OK	요청이 성공적으로 이루어짐
4XX	클라이언트 에러	400 Bad Request	잘못된 요청으로 서버에서 이해할 수 없는 요청임
		401 Unauthorized	인증 값이 유효하지 않음
		403 Forbidden	해당 인증 값의 권한으로는 접근할 수 없음
		404 Not Found	페이지를 찾을 수 없음
5XX	서버 에러	500 Internal Server Error	서버 내부 에러. 요청에 대한 처리 중 에러 발생
		503 Service Unavailable	현재 서버를 이용할 수 없음. 트래픽이 과도하거나 점검 중인 상태일 수 있음