RESTful API

'Restful API란?' 이라는 질문에 답변을 위한 REST API에 대한 내용을 정리해본다.

RESTful API는 결국 REST하다는 의미인데, 먼저 REST가 어떤 의미인지부터 알아야할 필요성이 있겠다.

 

1. REST API

REST API는 HTTP를 기반으로 클라이언트가 서버의 리소스에 접근하는 방식을 규정한 아키텍처

REST는 REpresentational State Transfer의 약자로, 자원(Resource)에 대한 요청을 행위(HTTP Method)로 처리한다.

주로 JSON, XML 형식의 데이터로 반환되어 처리된다.

 

1.1. REST의 구성

• 자원(Resource) - URI (엔드포인트)
• 행위(Verb) - HTTP Method (HTTP 요청 메서드)
• 표현(representations) - 페이로드 (JSON,XML 등의 포맷을 통해 전달)

 

1.2. REST의 특징

• Stateless(무상태성): 서버는 클라이언트의 상태를 유지하지 않는다. (서버는 클라이언트의 요청만을 처리)
• Cacheable(캐시 가능): 클라이언트는 서버의 응답을 캐싱처리 할 수 있다.
• Uniform Interface(일관된 인터페이스): 클라이언트와 서버 간의 인터페이스는 일관성 있게 설계되어야 한다.
• Layered System(계층 구조): 클라이언트는 서버와 직접 통신하는 대신 중간 계층(로드 밸런서, 캐시 등)을 통해 통신할 수 있다.
• Code on Demand(선택적 코드 전송): 서버에서 클라이언트로 실행 코드를 전송할 수 있다.

 

 

1.3. REST 설계 원칙

• HTTP URI를 통해 자원을 명시
• HTTP 메서드(GET,POST,PUT,DELETE)를 통해 행위 표현

위 두 가지가 잘 지켜졌을 때 RESTful하게 설계되었다고 할 수 있을 것 같다.

 

2. RESTful API

위에 나열한 REST의 기본 원칙을 잘 지킨 API를 RESTful API라고 정의한다.

 

 

3. HTTP 요청 메서드

어딘지 익숙한 GET, POST 등등의 메서드들!..

메서드	종류	목적	페이로드 필요여부
GET	index/retrieve	모든/특정 리소스 취득	x
POST	create	리소스 생성	o
PUT	replace	리소스의 전체 교체	o
PATCH	modify	리소스 일부 수정	o
DELETE	delete	모든/특정 리소스 삭제	x

PUT과 PATCH 같은 경우에는 둘 다 수정에 이용될 수 있지만,
PUT 같은 경우에는 리소스의 전체를, PATCH는 일부가 수정된다는 차이가 있다.

 

 

4. RESTful API 작성 예시

• URI에 동사를 포함하지 않고 HTTP Method로 대체하기

# bad
GET /todos/delete/1
GET /deleteTodos/1

# good
DELETE /todos/1javascript

• 소문자로 구성하기

# bad
/Todos/1

# good
/todos/1

• 파일 확장자 표시하지 않기

# bad
users/1/profile.png

# good
users/1/profile (Acceipt: image/png)

 

 

5. Restful API 외의 다른 API 아키텍처 스타일

5.1. SOAP API(Simple Object Access Protocol)

SOAP는 XML 기반의 메시지 교환 프로토콜이다.
SOAP API는 HTTP, HTTPS, SMTP 등의 프로토콜을 통해 데이터를 전송하며, 주로 XML 데이터 형식을 사용한다.

 

5.2. GraphQL API(Graph Query Language)

GraphQL은 페이스북에서 개발한 쿼리 언어다.
GraphQL API는 클라이언트에서 요청한 필드만을 반환하며, 여러 요청을 묶어 처리하는 기능 등을 제공한다.

이외에도 RPC API, WebSocket API 등이 있다.

 

 

6. 출처

https://aws.amazon.com/ko/what-is/restful-api/
https://pronist.dev/146#%EC%A0%95%EB%A0%AC%2C%20%ED%95%84%ED%84%B0%EB%A7%81%2C%20%ED%95%84%EB%93%9C%20%EC%84%A0%ED%83%9D-1

https://blog.bytebytego.com/p/why-is-restful-api-so-popular