REST API

이재연·2021년 4월 22일

REST API란?

REST API는 REST를 기반으로한 서비스 API이다.

REST

REST는 Representational State Transfer의 약자이다. 표현 상태 변경이라는 말인데, 쉽게 와닿지 않는다.

웹 클라이언트는 URL 같은 식별자(Resource Identifier)를 통해 자원(Resource)에 대해 요청을 하고 결과를 표출한다. 이 과정에서 클라이언트의 표현 상태(Representational State)가 변경(Transfer)된다. 자원은 웹이 제공하는 모든 정보 및 데이터를 의미하며, 식별자는 URI 같은 자원에 대한 링크이다.

REST는 이러한 아키텍처 디자인이다. 분산된 하이퍼미디어 시스템에서 사용하는 아키텍쳐 디자인 중 하나인 것이다.

REST 특징

REST는 자원, 행위, 표현으로 구성되며 아래의 특징을 갖는다.

HTTP 프로토콜을 사용하기 때문에 별도의 인프라 구축이 필요 없고, HTTP의 특성도 활용할 수 있다.
식별자를 이용하여 자원을 요청하며, 식별자는 HTTP URI이다.
HTTP 메소드를 사용한다.
JSON, XML, TEXT 등의 여러 형태로 통신한다. 주로 JSON, XML을 사용한다.

REST 제약조건

REST 는 아래의 6가지 제약조건을 만족시켜야 한다.

인터페이스 일관성 (Uniform Interface)
일관적인 인터페이스를 사용해야 한다.
URI를 사용하는 것 처럼 리소스를 식별하는 방법이 동일해야 한다.
특정 언어나 기술에 종속되지 않는, 표준에 의한 응답을 해야한다.
무상태 (Stateless)
클라이언트 정보를 서버에 저장하지 않는다.
세션 정보를 유지하지 않기 때문에 각 요청을 별개로 처리된다.
캐시 처리 가능 (Cacheable)
웹에서 사용하는 캐싱을 사용할 수 있다.
동일 서버에 다시 접근할 때 프록시 서버에 요청하여 빠른 응답처리가 가능하다.
계층화 (Layerd System)
다중 계층으로 구성될 수 있다.
클라이언트 혹은 서버에 미들웨어를 추가할 수 있다.
클라이언트와 서버는 시스템의 구조를 몰라도 통신이 가능해야 한다.
클라이언트-서버 구조 (Client-Server)
클라이언트와 서버는 서로 분리되어 독립적으로 기능을 수행한다.
주문형 코드 (Code on demand)
필수 조건은 아니다.
서버가 보낸 코드를 클라이언트에서 바로 실행 가능해야 한다.

HTTP Method

REST는 HTTP 메소드 중 GET, POST, PUT, DELETE 메소드를 사용한다.

GET
서버에 자원을 요청하는데 사용한다.
필요한 자원을 HTTP 패킷의 Header에 담아 요청한다.
POST
서버에 자원을 생성을 요청한다.
필요한 자원을 HTTP 패킷 Body에 담아 요청한다.
데이터 길이에 대한 제한이 없다.
브라우저에 의해 캐싱되지 않는다.
PUT
서버에 자원 수정을 요청한다.
DELETE
서버에 자원 삭제를 요청한다.

GET, PUT, DELETE는 같은 요청에 같은 결과를 반환하는 멱등성이 보장되어야 한다. 요청에 따라 결과가 달라진다면 POST를 사용하는 것이 좋다.

GET 보다 POST가 보안적인 측면에서 더 좋은가?
GET 방식은 요청 내용을 Header에 담아서 보내고 POST는 Body에 담아 보낸다. 때문에 URL에 노출이 되는지 차이만 있을뿐 차이는 없다.

REST API 설계

REST API를 설계할 때 아래의 규칙을 지키면 좋은 REST API를 만들 수 있다.

리소스 표현 방식

URI는 자원을 표현해야 한다.
소문자의 명사를 사용한다.

http://restapi.com/items/1 ⭕
http://restapi.com/get/items/1 ❌
http://restapi.com/ITEMS/1 ❌

/ 는 계층 관계를 나타내는데 사용한다.

http://restapi.com/games/lol/champions

URI는 / 로 끝나지 않아야 한다.

http://restapi.com/games/lol/champions/ ❌

_대신 -을 사용한다.

http://restapi.com/games/lol/patch-versions ⭕
http://restapi.com/games/lol/patch_versions ❌

연관 관계를 표현한다.

/자원/자원 ID/연관 관계의 자원

http://restapi.com/users/{userid}/matches

Collection은 복수로 표현, Document는 단수로 표현한다.

Document는 하나의 객체를 의미하고 Collection은 객체의 집합을 의미한다.
http://restapi.com/lol
http://restapi.com/lol/champions/1

자원 요청

자원에 대한 요청은 올바른 HTTP 메소드를 사용하여 요청한다.

GET : 자원 조회 요청
POST : 자원 입력 요청
PUT : 자원 수정 요청
DELETE : 자원 삭제 요청

HTTP 상태 코드

자원의 상태에 대한 올바른 코드를 사용해야 한다.

아래는 코드 분류와 자주 사용하는 코드이다.

1XX (조건부 응답)
2XX (성공)
200 : 요청을 정상적으로 수행함
201 : 요청한 자원을 성공적으로 생성함 (POST)
3XX (리다이렉션 완료)
301 : 요청한 자원의 URI가 변경됨 (Header에 변경된URI 반환)
4XX (요청 오류)
400 : 잘못된 요청
401 : 권한 없음, 사용자 인증이 필요한 요청(인증 실패)
403 : 금지됨, 사용자가 필요한 권한을 가지고 있지 않음 (인가 실패)
404 : 요청한 자원을 찾을 수 없음
405 : 허용되지 않는 방법, ex) POST 방식으로 받는 서버에 GET으로 요청을 보내는 경우
5XX (서버 오류)
500 : 서버에 문제가 있음