RESTful API 정의 및 사용 방법

REST

REST(Representational State Transfer)는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처를 의미하며, 아키텍처 스타일 원칙은 다음과 같다.

 

• 균일한 인터페이스 (Uniform Interface)
  동일한 리소스(정보)에 대한 모든 API 요청은 동일하게 보여야 한다. 따라서 표준 HTTP 메서드(GET, POST, PUT, DELETE등)을 사용하여 일관된 방식으로 리소스를 조작함으로써 시스템 간의 상호 운용성을 증가시킨다.
• 무상태(Statelessness)
  모든 HTTP 요청은 서로 독립적이므로 이전 요청의 상태 정보를 포함하지 않는다. 서버는 클라이언트의 상태를 유지하지 않고, 모든 필요한 정보는 해당 요청이 전송될 때 포함되어야 한다.
• 계층화 시스템
  계층화된 시스템 아키텍처에서 클라이언트는 클라이언트와 서버 사이에 존재하는 다른 승인된 중개자에게 연결할 수 있으며, 여전히 서버로부터도 응답을 받을 수 있다. 즉 통신 루프 사이에는 다수의 서로 다른 중개자가 존재할 수 있다. 클라이언트와 서버 모두, 자신이 end 애플리케이션이나 중개자와 통신하는지 여부를 알 수 없게 설계되었으므로 시스템의 확장성을 높이면서 보안을 강화한다.
• 캐시 가능성
  '캐싱'이란 서버 응답 시간을 개선하기 위해 클라이언트 또는 중개자에게 일부 응답을 저장하는 프로세스를 의미한다. 캐싱을 통해서 공통된 머리글/바닥글과 같이 중복되는 컨텐츠는 클라이언트/중개자에 저장함으로써 다시 전송될 필요가 없어진다. '캐시 가능' 또는 '캐시 불가능'으로 정의되는 API응답을 사용하여 캐싱을 제어할 수 있다.
• 온디맨드 코드
  온디맨드 코드(On-demand Code)는 클라이언트가 서버로부터 코드를 전송받아 실행할 수 있는 기능을 의미한다. 즉, 단순한 데이터만 주고받는 것이 아니라, 필요에 따라 실행 가능한 코드(예: 사용자 정의 등록 양식, 스크립트, 플러그인등)를 클라이언트에 전달할 수 있어야 한다.

REST API

REST API(Representational State Transfer)는 REST 아키텍처를 기반으로 서비스 API를 구현한 것을 의미한다. 3개의 요소인 자원, 행위, 표현으로 구성되며, REST API만으로도 HTTP 요청의 내용을 이해할 수 있다.

 

구성요소	내용	표현방법	예제
자원	자원	URI	`https://example.com/users/123`
행위	자원에 대한 행위	HTTP 요청 메서드	GET, POST, PUT, DELETE
표현	자원에 대한 행위의 구체적 내용	페이로드	데이터 형식(JSON, XML등)

*HTTP 요청에서의 페이로드 : 클라이언트가 서버로 데이터를 전송(POST,PUT)시 요청 본문(Body)에 포함된 데이터

*HTTP 응답에서의 페이로드 : 서버가 클라이언트 요청에 응답할 때 GET 요청에 대한 응답으로 반환되는 데이터
  (주로 JSON, XML형식으로 구조화된 상태)

REST API 기본 설계 원칙

1. URI는 리소스를 표현해야 한다.

동사보다는 명사를 사용해야 하기 때문에 get 과 같은 행위에 대한 표현이 들어가서는 안된다.

 

2. 리소스에 대한 행위는 HTTP 요청 메서드로 표현한다. 

HTTP 요청 메서드는 클라이언트가 서버에게 요청의 종류와 목적(리소스에 대한 행위)을 알리는 방법이다. GET, POST, PUT, PATCH, DELETE 요청 메서드를 사용하여 CRUD를 구현한다.

 

HTTP 요청 메서드	종류	목적	페이로드	비고
GET	index/retrieve	데이터 검색	X	검색에 필요한 매개변수를 URL의 쿼리 스트링으로 전달
POST	create	데이터 생성	O	데이터를 담은 페이로드를 요청 본문에 포함하여 전송
PUT	replace	데이터 전체 교체	O	교체될 데이터 전체를 요청 본문에 포함하여 전송
PATCH	modify	데이터 일부 수정	O	변경될 데이터 일부를 요청 본문에 포함하여 전송
DELETE	delete	데이터 삭제	X	삭제할 데이터는 URL을 통해 식별

 

위의 두 가지 원칙 외에도 '진정한' RESTful API 구현을 위해 추가적으로 고려해야할 사항은 존재한다. 예를 들어, URI는 자원들을 그룹화하여 계층적으로 표현해야 리소스간 관계를 명확하도록 API의 구조를 직관적으로 만들 수 있다. 그러나 /users/123/activate 와 같은 상태를 직접 나타내지 않고, 상태 변경을 표현하기 위해 PUT 또는 PATCH를 활용해야 한다.

 

/* PATCH 메서드 사용 방법 */
fetch('/users/123', {
    method: 'PATCH',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        email: "clay_updated@example.com"
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

/* PUT 메서드 사용 방법 */
fetch('/users/123', {
    method: 'PUT',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: "Clay Lee",
        email: "clay@example.com",
        isActive: true
    })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

 

또한 클라이언트에게 요청 결과를 명확하게 알리기 위해 HTTP 표준 상태코드를 적절히 사용해야 하며, URI 경로에 버전 번호를 포함시키거나 HTTP 헤더를 사용함으로써 지속적인 유지보수와 업데이트를 위한 버전관리도 필요하다.

 

특히 HATEOAS(헤이티오스)는 클라이언트가 서버와의 상호작용을 통해 동적으로 애플리케이션의 상태를 변경할 수 있도록 하는 데, 이를 위해 응답에 하이퍼미디어 링크를 포함시키는 것이 중요하다. 즉, RESTful API에서 사용자 정보를 가져오는 GET 요청에 대한 응답이 HATEOAS 원칙을 따른다면, 사용자 정보 외에도 해당 사용자와 관련된 다른 액션을 수행할 수 있는 링크가 존재한다. 

 

GET /users/123

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": {
      "href": "/users/123"
    },
    "orders": {
      "href": "/users/123/orders"
    },
    "update": {
      "href": "/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "/users/123",
      "method": "DELETE"
    }
  }
}

 

위의 예제에서 _links 객체는 클라이언트가 수행할 수 있는 다양한 작업들에 대한 링크를 제공한다. self 링크는 자기 자신의 리소스에 대한 링크를, orders 링크는 사용자의 주문 목록을 조회할 수 있는 링크를, update와 delete 링크는 사용자 정보를 수정하거나 삭제할 수 있는 링크와 그에 대한 HTTP 메서드를 제공한다.

 

이와 같이 클라이언트는 HATEOAS를 통해 서버의 API 구조를 사전에 알 필요 없이, 응답으로부터 다음 가능한 상태 전이를 파악하고 해당 액션을 수행할 수 있게 되는 것이다. 이는 클라이언트와 서버의 결합도를 낮추고, 서버의 변경이 클라이언트에 미치는 영향을 최소화시킨다.

 

REST API / RESTful API

RESTful API는 REST 설계 원칙을 완벽하게 준수하는 API를 의미한다. 이는 모든 RESTful API는 REST API지만, 모든 REST API가 RESTful하지 않다는 것을 의미한다. 즉, REST 원칙을 기반으로 하되 모든 원칙을 엄격하게 준수하지 않는 API는 REST API로 불릴 수 있지만, RESTful라고 할 수 없는 것이다.

 

---

마치며

그동안 자바스크립트를 공부하면서 RESTful API란 'CRUD를 이용한 API 설계'라고만 생각했었다. 이번 블로그를 작성하면서 REST API와 RESTful API의 차이점을 명확하게 정리할 수 있었지만, 동시에 진정한 RESTful API 구현을 위해 공부해야할 양도 많다는 것을 알 수 있었다. 본문에 언급한 HATEOAS외에도 RESTful API를 만족시키는 설계 원칙들에 대해서는 추후 복습할 때 한 번 더 정리해야겠다.

 

---

참고 문헌

1. aws, RESTful API란 무엇인가요? : https://aws.amazon.com/ko/what-is/restful-api/

2. 이웅모, 모던자바스크립트 44장.REST API (p830~p841)

3. levi.log, RESTful API란 : https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

4. 슬기로운 개발생활, HATEOAS까지 사용해야 완벽한 RESTful이다. : https://dev-coco.tistory.com/187