웹/네트워크/HTTP 베이스캠프

RESTful API

RESTful API는 개발자들 사이에서 정보를 주고받기 위한 표준화된 형식으로, 어떤 문법이 아닌 형식이기 때문에 언어에 구애받지 않고 사용되는 일종의 개발 철학이라고 생각할 수 있습니다. 이번 챕터에서는 RESTful API 설계 원칙에서 대해 살펴보는 것이 아니라 RESTful API가 무엇인지에 대해 가볍게 살펴보는 시간을 가져보겠습니다. 권장하고 있는 설계 원칙은 마이크로소프트의 문서를 첨부합니다.

웹 API 디자인 모범 사례 - Azure Architecture Center

RESTful API는 Representational State Transfer Application programing interface 의 약자입니다. 한국말로 직역하면 ‘표현적인 상태로 전송하게 만드는 앱 프로그래밍 수단’ 정도로 해석할 수 있겠습니다. 여기서 ‘표현적인 상태’란 API 의 형태만으로도 기능을 짐작할 수 있는 상태를 말하며, RESTful API의 핵심은 단순히 어떤 기능을 구동하기 위한 API요청이 아닌, API 요청 방식의 모습만으로도 어떤 기능을 수행할지 예상 가능하다는 점에 있습니다.

우리가 앞서 배운 HTTP 구조로 예를 들어보도록 하겠습니다.

GET /books?year=2024 HTTP/1.1
Host: weniv.co.kr

GET /books?year=2024 HTTP/1.1
Host: weniv.co.kr

위의 예시는 2024년에 출시된 도서 목록을 조회하는 RESTful API 요청입니다. GET 메서드를 사용하여 /books 리소스에 접근하고, 쿼리 파라미터 year를 통해 2024년을 지정했습니다. 이러한 형식의 API 요청은 직관적이며, 요청의 의도를 명확하게 전달할 수 있습니다.

이렇게 URL로 원하는 자원을 명시하고 적절한 HTTP 메서드를 사용하여 해당 자원의 요청사항을 반환하는 URL 설계 철학을 RESTful API 라고 볼 수 있습니다.

예를 들어 아래와 같이 자원이 아닌 행위가 URL에 포함되는 것은 RESTful하다 얘기하지 않습니다.

// Bad
GET /books/delete/1 HTTP/1.1
Host: weniv.co.kr
 
// Good
DELETE /books/1 HTTP/1.1
Host: weniv.co.kr

// Bad
GET /books/delete/1 HTTP/1.1
Host: weniv.co.kr
 
// Good
DELETE /books/1 HTTP/1.1
Host: weniv.co.kr

RESTful API를 사용하는 것을 은행에 가서 계좌를 찾고, 잔고를 보고, 돈을 인출하는 과정에 비유할 수 있습니다.

계좌 찾기 (GET 요청): 은행에 가서 특정 계좌를 찾듯이, API를 통해 데이터(계좌)를 요청하면 서버(은행)가 그 데이터(계좌)를 찾아 응답으로 보내줍니다.
```
fetch('https://api.example.com/account/111-111-3333');
```
```
fetch('https://api.example.com/account/111-111-3333');
```

돈 입금하기 (POST 요청): 새로운 돈을 계좌에 넣듯, 새로운 데이터를 서버에 추가할 수 있습니다. 서버는 새 데이터를 받아 저장하고 성공적으로 추가되었다는 응답을 보냅니다.

fetch('https://api.example.com/account/111-111-3333', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		action: 'deposit',
		price: '100,000,000'
	});
});

fetch('https://api.example.com/account/111-111-3333', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({
		action: 'deposit',
		price: '100,000,000'
	});
});

출금하기 (PUT 요청): 돈이 필요한 경우 출금하여 계좌 잔액 정보를 업데이트하는 것처럼, 기존의 데이터를 수정할 수 있습니다.

fetch('https://api.example.com/account/111-111-3333', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'withdraw',
    price: '1,000,000,000'
  });
});

fetch('https://api.example.com/account/111-111-3333', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'withdraw',
    price: '1,000,000,000'
  });
});

계좌 삭제하기 (DELETE 요청): 은행에서 계좌를 제거하는 것처럼, 서버에서 특정 데이터를 삭제할 수 있습니다.

fetch('https://api.example.com/account/111-111-3333', {
  method: 'DELETE'
});

fetch('https://api.example.com/account/111-111-3333', {
  method: 'DELETE'
});

백엔드 개발자가 이러한 API 설계와 구현, 문서화를 해놓으면 프론트엔드 개발자가 그 문서를 보고 개발하게 됩니다.

아래 예시는 교육용으로 만들어 놓은 API 명세입니다. 다만 실무에서도 이 RESTful API 작성 원칙을 모두 지키지 않기 때문에, 모든 규칙들이 다 지켜지면서 만든 API 명세는 아닙니다. 이렇게 협업한다는 사실만 참고해주세요.

위니브 샘플 API 명세

이러한 문서화가 매우 어렵기 때문에 스웨거와 같은 문서화 도구를 사용합니다. 다만 그러한 문서화 도구를 사용하더라도 이정도 상세의 문서가 나와야 합니다.