REST API란? RESTful한 API 만드는 법

REST란?

REST(Representational State Transfer)는 2000년 로이 필딩의 박사 학위 논문에서 소개된 용어

자원을 정의한 후 해당 자원의 상태(정보)를 주고 받는 행위를 말한다.

 

RESTful이란?

REST 아키텍처를 지켜 구현된 시스템을 RESTful이란 용어로 지칭한다.

---

REST 아키텍처에 적용되는 6가지 기본 원칙

1. 클라이언트 - 서버 구조

클라이언트 - 서버를 분리하여 각 파트가 독립적으로 운영되므로 의존성이 줄어든다. 다양한 플랫폼에서의 이식성이 개선되며 서버 아키텍처를 단순화하여 확장성이 개선된다. 클라이언트는 리소스 URI 외의 정보가 필요하지 않으며 서버와 클라이언트는 인터페이스가 변경되지 않는 한 독립적으로 교체 및 개발이 가능하다

 

2. 무상태

클라이언트에서 서버로의 각 요청은 서버에 저장되는 것이 아닌 단순한 요청 처리만 해야 한다. 상호작용이 상태 비저장이므로 모든 요청을 새롭게 처리하며 클라이언트에서 사용자 상태 저장이 필요한 경우에는 클라이언트의 각 요청에 인증 및 권한 부여를 포함하여 요청을 처리하는데 필요한 모든 정보가 포함되어야 한다

 

3. 캐시 가능

클라이언트는 응답을 캐싱할 수 있어야 한다. GET 요청은 특별한 조건이 발생할 때까지 기본적으로 캐싱 가능해야 하며 일반적으로 브라우저는 모든 GET 요청을 캐시 가능한 것으로 처리한다.

POST 요청은 원칙적으로는 캐싱이 불가능하지만 캐시를 허용하는 지시문이 있는 Expires헤더 또는 Cache-Control헤더를 응답에 추가하면 캐싱이 가능해진다. PUT,DELETE 요청은 캐싱 불가능

 

4. 일관된 인터페이스

구성 요소에 아키텍처 제약 조건을 가지고 일관된 인터페이스를 적용함으로서 아키텍처 단순화 및 상호 작용의 가시성 향상

모든 리소스는 HTTP GET과 같은 일반적인 접근 방식을 통하여 접근이 가능해야 하며, 일관된 접근 방식을 사용하여 유사하게 수정해야 함

단일 리소스는 너무 크지 않아야 하며 표현에 모든 것을 포함하여야 함. 리소스에는 관련 정보를 가져오기 위한 상대 URI 링크(HATEOAS)가 포함되어야 함. 시스템 전체의 리소스 표현은 명명 규칙, 리소스 형식, 데이터 형식(XML/JSON)과 같은 특정 지침을 따라야 함

 

5. 계층형 시스템

아키텍처를 계층형으로 구성. 각 구성 요소가 상호작용을 하는 직접적인 계층 너머를 볼 수 없도록 동작을 제한하며 중간 서버는 로드 밸런싱, 공유 캐시 기능을 제공하여 시스템 확장성에 용이함. 클라이언트는 서버에 직접 연결되어 있는지 중간에 연결되어 있는지 알 수 없음

 

6. 주문형 코드(옵션)

자바 애플릿, 자바스크립트 코드 다운로드 및 실행으로 클라이언트 기능 확장, 사전 구현에 필요기능 수를 줄여 클라이언트 단순화

---

RESTful한 API 만들기

 

1. 자원을 나타내는 명사 사용

리소스 URI는 동사 대신 명사를 사용하여야 한다 

/games/runnung       X /games/status          O

 

2. 일관성 있는 이름 규칙

슬래시(/)를 사용하여 계층 관계를 나타낸다

/games /games/status

URI 마지막에 슬래시(/)를 넣지 않는다

/games/status/         X /games/status          O

하이픈(-)을 사용하여 가독성을 높인다

/games/installGame           X /games/install-game          O

밑줄(_)을 사용하지 않는다

/games/install_game           X /games/install-game          O

URI에 소문자를 사용한다

/games/STATUS          X /games/status            O

파일 확장자를 사용하지 않는다

/games/status.xml      X /games/status            O

 

3. URI에 CRUD 행위 포함 금지

URI에 작업을 표시하지 않는다. 

X	O
/games/install-game/list /games/install-game/create /games/install-game/update /games/install-game/delete	GET         /games/install-game POST       /games/install-game PUT         /games/install-game/{data} DELETE   /games/install-game/{data}

 

4. 수행되는 기능에 맞게 HTTP Method를 사용해야 한다

GET, POST, PUT, DELETE, PATCH Method가 있으며, 이 중 GET, POST, PUT, DELETE는 반드시 제공해야 한다.

*POST 하나로 CRUD를 전부 수행하는 것은 RESTful API가 아니다!

HTTP Method	기능
GET	자원 조회
POST	자원 등록
PUT	자원에 대한 등록 / 전체 수정
PATCH	자원의 일부를 수정
DELETE	자원 삭제

X	O
POST    /games/install-game/list POST    /games/install-game/create POST    /games/install-game/update POST    /games/install-game/delete	GET         /games/install-game POST       /games/install-game PUT         /games/install-game/{data} DELETE   /games/install-game/{data}

 

PUT과 PATCH의 차이점

PUT은 자원 전체 수정, PATCH는 자원 일부를 수정한다.

동일한 수정 작업을 하고자 할 때, PUT과 PATCH는 다음과 같은 차이가 있다.

games table
id	name	price
1	pokemon	60000
2	supermario	70000

PUT
요청	결과
PUT         /games/install-game/1 data : { "price" : 65000 }	data {       "name" : null,       "price" : 65000 }

전체가 수정되므로 보내지 않은 값은 null로 입력된다. PUT으로 수정 작업을 하려면, 전체 데이터를 전송해야 한다.

PUT
요청	결과
PUT         /games/install-game/1 data : { "name" : "pokemon", "price" : 65000 }	data {       "name" : "pokemon",       "price" : 65000 }

 

PATCH는 자원의 일부를 수정하므로 이렇게 사용이 가능하다.

PATCH
요청	결과
PUT         /games/install-game/1 data : { "price" : 65000 }	data {       "name" : "pokemon",       "price" : 65000 }

PUT처럼 전체 자원을 보낼 필요 없이, 수정될 자원만 전송하여 수정 작업을 하므로 데이터 전송이 훨씬 간결해진다.

PUT은 전체 자원을 수정할 때, PATCH는 자원의 일부를 수정할 때 사용하도록 한다.

 

5. 응답에 대한 메타데이터는 HTTP Status에 포함되어야 한다

응답에 대한 상태코드는 HTTP Status에 전달한다. Body에는 요청에 대한 데이터만 전달한다.

또한, 응답에 대한 정확한 상태코드를 HTTP Status에 전달해 주어야 한다.

상태코드는 1xx~5xx까지 존재하지만 일부 코드만 소개한다.

 

2xx 코드 : 성공. 클라이언트의 요청이 성공적으로 수락되었다는 코드

상태 코드	설명
200 OK	요청 성공
201 Create	요청이 성공하여 새로운 리소스가 생성됨
202 Accepted	요청이 수신되었지만 아직 완료되지 않았음. 일반적으로 요청을 완료하는데 시간이 걸리는 작업에서 응답됨
204 No Content	요청이 성공하였으나 Body에 전달할 데이터가 없는 경우(예:DELETE 작업)

4xx 코드 : 클라이언트 오류로 인한 실패

상태 코드	설명
400 Bad Request	클라이언트가 잘못된 구문으로 요청하여 서버가 요청을 이해할 수 없는 경우
401 Unauthorized	인증이 필요한 요청에 인증정보 없이 요청한 경우(로그인이 필요한 리소스에 요청한 경우)
403 Forbidden	클라이언트가 요청에 대한 액세스 권한이 없는 경우(401과 달리 인증 유무와 관계 없음)
404 Not Found	서버가 요청된 리소스를 찾지 못할 경우
405 Method Not Allowed	요청한 HTTP Method가 비활성화 된 경우(예: GET Method만 허용된 요청에 POST Method를 요청할 경우) 405 응답에는 리소스가 지원하는 HTTP Method를 Allow Header에 포함해야 함

5xx 코드 : 서버 오류로 인한 실패

상태 코드	설명
500 Internal Server Error	서버 오류로 인하여 요청을 수행하지 못한 경우

 

참고

restfulapi.net/tutorial/rest/

sanghaklee.tistory.com/57

meetup.toast.com/posts/92