44장 REST API
**REST(Representational State Transfer)**는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처다. REST API는 REST를 기반으로 서비스 API를 구현한 것을 의미하며, REST의 기본 원칙을 성실히 지킨 서비스 디자인을 RESTful이라 한다.
44.1 REST API의 구성
REST API는 자원(Resource), 행위(Verb), 표현(Representation)의 3가지 요소로 구성된다.
| 구성 요소 | 내용 | 표현 방법 |
|---|---|---|
| 자원 (Resource) | 자원 | URI (엔드포인트) |
| 행위 (Verb) | 자원에 대한 행위 | HTTP 요청 메서드 |
| 표현 (Representation) | 자원에 대한 행위의 구체적 내용 | 페이로드 |
44.2 REST API 설계 원칙
REST API를 설계할 때 가장 중요한 두 가지 원칙은 다음과 같다.
-
URI는 리소스를 표현해야 한다.
- 리소스를 식별할 수 있는 이름은 동사보다는 명사를 사용한다.
# bad GET /getTodos/1 GET /todos/show/1 # good GET /todos/1 -
리소스에 대한 행위는 HTTP 요청 메서드로 표현한다.
- HTTP 요청 메서드는 클라이언트가 서버에게 요청의 종류와 목적을 알리는 수단이다.
HTTP 요청 메서드 종류 목적 페이로드 GET index/retrieve 모든/특정 리소스 취득 X POST create 리소스 생성 O PUT replace 리소스의 전체 교체 O PATCH modify 리소스의 일부 수정 O DELETE delete 모든/특정 리소스 삭제 X # bad: URI에 행위(delete)를 명시함 GET /todos/delete/1 # good: URI는 리소스만 표현하고 행위는 HTTP 메서드(DELETE)로 표현함 DELETE /todos/1
44.3 JSON Server를 이용한 REST API 실습
JSON Server는 json 파일을 이용하여 빠르고 간편하게 가상 REST API 서버를 구축할 수 있는 툴이다.
44.3.1 JSON Server 설치
$ npm install json-server --save-dev44.3.2 db.json 파일 생성
프로젝트 루트에 db.json 파일을 생성한다.
{
"todos": [
{
"id": 1,
"content": "HTML",
"completed": true
},
{
"id": 2,
"content": "CSS",
"completed": false
},
{
"id": 3,
"content": "Javascript",
"completed": true
}
]
}44.3.3 JSON Server 실행
package.json의 scripts에 실행 스크립트를 추가한다.
"scripts": {
"start": "json-server --watch db.json"
}터미널에서 npm start로 서버를 실행한다. 기본 포트는 3000이다.
44.3.4 GET 요청
todos 리소스에서 모든 todo를 취득(index)하거나 id를 사용하여 특정 todo를 취득(retrieve)한다.
// XMLHttpRequest 객체 생성
const xhr = new XMLHttpRequest();
// HTTP 요청 초기화
// GET /todos : 모든 todo 취득
xhr.open('GET', '/todos');
// HTTP 요청 전송
xhr.send();
xhr.onload = () => {
if (xhr.status === 200) {
console.log(JSON.parse(xhr.response));
} else {
console.error('Error', xhr.status, xhr.statusText);
}
};44.3.5 POST 요청
todos 리소스에 새로운 todo를 생성한다.
const xhr = new XMLHttpRequest();
// POST /todos : 새로운 todo 생성
xhr.open('POST', '/todos');
// 클라이언트가 서버로 전송할 데이터(페이로드)의 MIME 타입 지정
xhr.setRequestHeader('content-type', 'application/json');
// HTTP 요청 전송
// 새로운 todo를 생성하기 위해 페이로드를 서버에 전송해야 한다.
xhr.send(JSON.stringify({ id: 4, content: 'Angular', completed: false }));
xhr.onload = () => {
// 200(OK) 또는 201(Created)
if (xhr.status === 200 || xhr.status === 201) {
console.log(JSON.parse(xhr.response));
} else {
console.error('Error', xhr.status, xhr.statusText);
}
};44.3.6 PUT 요청
특정 리소스 전체를 교체할 때 사용한다.
const xhr = new XMLHttpRequest();
// PUT /todos/4 : id가 4인 todo를 교체
xhr.open('PUT', '/todos/4');
xhr.setRequestHeader('content-type', 'application/json');
// 리소스 전체 교체 (payload에 포함되지 않은 프로퍼티는 삭제될 수 있음 주의)
xhr.send(JSON.stringify({ id: 4, content: 'React', completed: true }));
xhr.onload = () => {
if (xhr.status === 200) {
console.log(JSON.parse(xhr.response));
} else {
console.error('Error', xhr.status, xhr.statusText);
}
};44.3.7 PATCH 요청
특정 리소스의 일부를 수정할 때 사용한다.
const xhr = new XMLHttpRequest();
// PATCH /todos/4 : id가 4인 todo의 일부 수정
xhr.open('PATCH', '/todos/4');
xhr.setRequestHeader('content-type', 'application/json');
// 리소스 일부 수정 (completed만 수정)
xhr.send(JSON.stringify({ completed: false }));
xhr.onload = () => {
if (xhr.status === 200) {
console.log(JSON.parse(xhr.response));
} else {
console.error('Error', xhr.status, xhr.statusText);
}
};44.3.8 DELETE 요청
todos 리소스에서 id를 사용하여 특정 todo를 삭제한다.
const xhr = new XMLHttpRequest();
// DELETE /todos/4 : id가 4인 todo 삭제
xhr.open('DELETE', '/todos/4');
// DELETE 요청은 페이로드를 전송하지 않는다.
xhr.send();
xhr.onload = () => {
if (xhr.status === 200) {
console.log(JSON.parse(xhr.response));
} else {
console.error('Error', xhr.status, xhr.statusText);
}
};과제: 퀴즈
퀴즈 1
REST API의 3가지 구성 요소는 무엇인가?
정답 및 해설
정답: 자원(Resource), 행위(Verb), 표현(Representation)
해설: REST API는 자원(URI), 행위(HTTP 요청 메서드), 표현(페이로드)으로 구성되어, 직관적이고 표준화된 방식으로 리소스를 다룰 수 있게 합니다.
퀴즈 2
REST API 설계 원칙 중, 리소스에 대한 행위는 무엇으로 표현해야 하는가?
정답 및 해설
정답: HTTP 요청 메서드 (GET, POST, PUT, DELETE, PATCH 등)
해설:
URI에는 리소스(명사)만 포함되어야 하며, delete, create와 같은 행위(동사)가 포함되어서는 안 됩니다. 행위는 HTTP 메서드를 통해 명명백백하게 표현해야 합니다.
퀴즈 3
HTTP 요청 메서드 중 PUT과 PATCH의 차이점은 무엇인가?
정답 및 해설
정답: PUT은 리소스 전체 교체, PATCH는 리소스 일부 수정.
해설:
PUT: 해당 리소스를 요청 페이로드로와 완전히 교체합니다. 만약 페이로드에 없는 필드가 있다면 null이나 초기값으로 변경될 수 있습니다(구현에 따라 다름).PATCH: 해당 리소스의 일부분만 변경합니다. 페이로드에 포함된 필드만 업데이트됩니다.
퀴즈 4
JSON Server를 사용하여 db.json을 감지(watch)하며 실행하는 명령어는?
정답 및 해설
정답: json-server --watch db.json (또는 npm start로 설정한 스크립트)
해설:
--watch 옵션을 사용하면 db.json 파일의 변경 사항을 실시간으로 감지하여 서버에 반영합니다.
퀴즈 5
RESTful API 설계에서 GET /todos/delete/1과 같은 URI가 권장되지 않는 이유는?
정답 및 해설
정답: URI에 ‘delete’라는 행위(동사)가 포함되어 있기 때문이다.
해설:
REST 설계 원칙에 따르면 URI는 리소스(자원)를 명사로 표현해야 하며, 행위는 HTTP 메서드(DELETE)로 표현해야 합니다. 따라서 DELETE /todos/1이 올바른 표현입니다.