REST API와 RESTful API는 서로 다르다.
굳이 이야기하자면
REST API는 RESTful API를 위한 필요조건이고
RESTful API는 REST API를 위한 충분조건이다.
REST API는
이 용어는 "REST"의 기본 아이디어를 따르는 API를 가리킨다.
REST는 "Representational State Transfer"의 약어로, 자원을 표현하고 해당 자원에 대한 상태(데이터)를 전달하는 아키텍처 스타일이다.
REST API는 이러한 원칙을 따르는 API를 의미하며, 다음과 같은 특징을 갖는다.
자원(리소스)을 고유한 URI(Uniform Resource Identifier)로 식별한다.
HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원을 조작한다.
상태를 전달하는데 JSON 또는 XML과 같은 데이터 형식을 사용한다.
상태를 변경하기 위해 CRUD(Create, Read, Update, Delete) 작업을 수행한다.
RESTful API는
이 용어는 REST 아키텍처 스타일을 완전히 따르고 있는 API를 가리킨다.
즉, RESTful API는 엄격한 REST 원칙을 준수하는 API를 의미하며, REST의 모든 특성과 규칙을 따르는 것을 강조한다.
이러한 API는 다음과 같은 특징을 가진다.
자원을 URI로 나타내고, HTTP 메서드를 사용하여 조작한다.
상태를 전달할 때 HTTP 상태 코드를 사용하여 응답합니다.
Self-descriptive로서, API 자체가 사용 가능한 자원 및 작업에 대한 정보를 제공한다.
Stateless로서, 각 요청은 서버에 대한 모든 필요한 정보를 포함하며, 세션 상태를 유지하지 않는다.
요약하면, RESTful API는 REST 아키텍처 스타일의 엄격한 준수를 강조하는 것이다.
REST API는 REST 원칙을 따르는 API를 일반적으로 가리키는 더 포괄적인 용어다.
RESTful API는 REST API의 한 종류로 볼 수 있다.
REST API를 설계하는 법
아, 그 전에 API가 뭔지 알아보고 가자.
API(Application Programming Interface)는 다른 소프트웨어 응용 프로그램과 상호 작용하기 위한 규칙과 도구의 모음이다.
서로 다른 소프트웨어 시스템 또는 컴포넌트 간에 통신하고 상호 작용할 수 있도록 해 주는 방법이기도 하다.
예를 들어,
자국어만 사용할 수 있는 독일인과 미국인은 언어로 소통할 수 없다.
둘이 언어로 소통하려면 통역가 또는 상대의 언어 사전 등이 필요하다.
이와 같이, 서로 다른 것끼리 교통할 수 있게 합의점을 마련해 주는 것, 그것이 인터페이스(API 등)라고 할 수 있다.
API는...
상호 연결성 및 통합: 다른 시스템 또는 서비스와 상호 작용하여 데이터를 공유하고 서비스를 이용할 수 있게 한다.
기능 확장: 다른 소프트웨어 개발자가 기존 소프트웨어를 확장하고 새로운 기능을 추가할 수 있도록 한다.
서비스 제공: 다른 개발자나 소프트웨어에 기능을 제공하는 서비스로 사용된다.
API는 웹 API, 라이브러리 API, 운영 체제 API 등 형태가 다양하다.
웹 API는 웹 서비스를 통해 다른 시스템과 통신하기 위해 사용되며, 주로 HTTP를 통해 요청과 응답을 처리한다. 예를 들어, 소셜 미디어 플랫폼의 API로는 사용자 데이터를 검색하거나 업로드할 수 있다.
API는 개발자나 개발팀이 다른 소프트웨어와 통합하고 상호 작용하는 데 필수적인 도구로, 다양한 애플리케이션 및 서비스가 서로 연결되고 작동할 수 있도록 한다.
이런 API를 설계하려면 아키텍처가 필요하다.
API 아키텍처 종류로는 무엇이 있을까?
다음은 주요 API 아키텍처 유형 중 일부이다:
REST (Representational State Transfer): RESTful 아키텍처는 자원을 URI(Uniform Resource Identifier)로 표현하고 HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 자원을 조작하는 아키텍처 스타일이다. REST는 간단하고 확장 가능하며, 웹 API의 표준으로 널리 사용된다.
SOAP (Simple Object Access Protocol): SOAP는 XML 기반의 프로토콜로, 웹 서비스 간에 데이터를 교환하기 위해 사용된다. SOAP는 보안 및 트랜잭션 처리와 같은 고급 기능을 제공하며, 표준화된 스펙으로 정의되어 있다.
GraphQL: GraphQL은 Facebook에서 개발한 쿼리 언어 및 런타임 환경으로, 클라이언트가 원하는 데이터를 직접 요청할 수 있는 유연한 데이터 쿼리 언어다. GraphQL은 RESTful API에 비해 더 많은 제어와 효율성을 제공한다.
gRPC: gRPC는 Google에서 개발한 고성능 RPC(Remote Procedure Call) 프레임워크로, Protocol Buffers를 사용하여 데이터를 직렬화하고 HTTP/2를 통해 통신한다. 이는 분산 시스템 간 효율적인 통신을 지원하며, 다양한 언어로 클라이언트 및 서버를 구현할 수 있다.
JSON-RPC 및 XML-RPC: JSON-RPC 및 XML-RPC는 원격 프로시저 호출(RPC)을 위한 간단한 프로토콜로, 클라이언트가 원격 서버에서 함수를 호출하고 결과를 받을 수 있도록 한다.
WebSocket: WebSocket은 양방향 통신을 지원하는 프로토콜로, 클라이언트 및 서버 간 실시간 데이터 스트리밍을 지원합니다. 주로 실시간 채팅 및 게임 애플리케이션에서 사용된다.
OData: OData는 RESTful 웹 서비스를 설계하고 구현하기 위한 프로토콜 및 규격입니다. OData를 사용하면 데이터베이스와 연결된 웹 서비스를 구축하고 쿼리할 수 있다.
SOAP REST Hybrid: 이러한 아키텍처는 SOAP와 REST를 혼합하여 사용하는 것으로, 기존의 SOAP 웹 서비스를 RESTful 웹 서비스로 감싸거나 역으로 RESTful 서비스를 SOAP로 래핑하는 방식입니다.
다시 REST API로 돌아가자.
그래서 REST API는 어떻게 설계하는 것인가?
1) 리소스 식별
API를 설계하기 전에 어떤 리소스(데이터 또는 엔티티)를 제공할지 식별해야 한다.
리소스는 고유한 URI(Uniform Resource Identifier)로 식별되어야 한다.
예를 들어, 블로그 애플리케이션의 경우 "게시물"이나 "댓글"과 같은 리소스를 고려할 수 있다.
2) HTTP 메서드 지정
각 리소스에 대한 CRUD(Create, Read, Update, Delete) 작업을 어떤 HTTP 메서드(GET, POST, PUT, DELETE)로 수행할 것인지 결정한다. 일반적으로 다음과 같이 매핑된다.
GET: 리소스 읽기
POST: 새로운 리소스 생성
PUT: 리소스 업데이트 (전체 리소스 교체)
PATCH: 리소스 부분 업데이트
DELETE: 리소스 삭제
3) URI 설계
리소스마다 고유한 URI를 설계한다.
URI는 명확하고 직관적이어야 하며 계층 구조로 표현할 수 있다.
예를 들어, 게시물은 "/posts"와 같은 URI에 접근할 수 있다.
4) 데이터 포맷 선택
클라이언트와 서버 간 데이터 교환 형식을 선택한다.
일반적으로 JSON 또는 XML을 사용한다.
요즘에는 JSON이 더 널리 사용되는 경향이 있다.
5) HTTP 상태 코드 활용
서버는 적절한 HTTP 상태 코드를 반환하여 클라이언트에 요청 결과를 알려준다.
예를 들어, 200(OK), 201(Created), 204(No Content), 400(Bad Request), 404(Not Found), 500(Internal Server Error) 등을 사용할 수 있다.
6) 에러 처리
API에서 예외 또는 오류를 처리하는 방법을 정의한다.
에러 응답은 구조화되어야 하며, 클라이언트에 유용한 정보를 제공해야 한다.
7) 보안 고려
API 보안을 위해 인증 및 권한 부여 메커니즘을 구현한다.
HTTPS를 사용하여 데이터의 안전성을 보장하는 것도 중요하다.
8) 버전 관리
API 버전 관리를 통해 이전 버전과 호환성을 유지하면서 새로운 기능을 추가할 수 있다.
버전은 URI 또는 헤더를 통해 지정된다.
9) 문서화
API를 문서화하여 개발자가 쉽게 이해하고 사용할 수 있도록 한다. Swagger, API Blueprint, 또는 기타 문서화 도구를 사용할 수 있다.
10) 테스트 및 검증
API를 테스트하고 검증하여 실제 사용 시에 안정적으로 동작하는지 확인한다.
11) 성능 최적화
API의 성능을 최적화하고 캐싱, 압축, 비동기 처리 등을 고려한다.
12) 보안 검토
보안 전문가와 함께 API를 검토하고 취약점을 해결한다.
API 설계는 중요하다.
잘 설계된 API는 개발자 및 클라이언트가 원활하게 상호 작용할 수 있도록 한다.
설계 단계에서 충분한 고민과 검토를 통해 API를 구현해야 향후 유지 보수 및 확장이 더 쉬워진다.
'좋은' REST API 설계법이 있을까?
바로 위에 있는 단계만 잘 따라도 좋은 API를 설계할 수 있다.
아래는 내가 만든 REST API 설계 샘플이다.
전체 코드는 공개하지 않는다.
어디까지나 예시다.
1) 게시글에 대한 모델 클래스를 만든다.
public class ArticleDto {
private int articleId;
private String title;
private String content;2) API 컨트롤러를 만든다.
@RestController
@RequestMapping("/articles")
public class ArticleController {3) 컨트롤러 클래스 아래 API 엔드포인트를 정의한다.
@GetMapping
public List<ArticleDto> getAllArticles()4) API 로직을 구현한다.
@GetMapping("/{articleId}")
public ResponseEntity<ArticleDto> getArticleById(@PathVariable int articleId) {
ArticleDto article = articleService.getArticleById(articleId);
if (article != null) {5) HTTP 상태 코드를 설정한다.
@PostMapping("/")
public ResponseEntity<Post> createPost(@RequestBody Post post) {
// 게시물 생성 로직을 추가하고 적절한 상태 코드와 함께 반환하세요
return ResponseEntity.status(HttpStatus.CREATED).body(newPost);
}6) 테스트한다.
나는 보통 Postman을 사용한다.
