Pink Spider/REST API

Rest API란 무엇이며, RestFul 하다는 건 어떤 의미인가?

REST API와 RESTful의 개념은 웹 개발에서 자주 등장하지만, 처음 접하면 헷갈릴 수 있어요. 쉽게 풀어서 설명해볼게요.

🔹 REST API란?

REST는 “REpresentational State Transfer"의 약자예요. 2000년에 로이 필딩(Roy Fielding)이 논문에서 제안한 웹 아키텍처 스타일 중 하나죠.

즉, REST API는 이 REST 원칙에 따라 설계된 웹 API를 말해요.

🔹 REST의 핵심 개념

REST는 다음의 6가지 제약 조건을 기반으로 해요:

클라이언트-서버 구조
- 클라이언트(브라우저, 앱)와 서버는 서로 분리되어 역할을 나눔.
무상태성 (Stateless)
- 서버는 클라이언트의 요청 간 상태를 저장하지 않음. 매 요청마다 필요한 정보가 다 포함되어야 해요.
캐시 처리 가능
- 응답은 캐시가 가능해야 함. 클라이언트 성능 향상.
계층화 구조
- 클라이언트는 중간 서버가 있는지 몰라도 됨.
인터페이스 일관성 (Uniform Interface)
- 자원에 접근하는 방식이 일관되어야 함.
Code on Demand (선택 사항)
- 서버는 클라이언트에게 실행할 코드를 전달할 수 있음 (잘 안 씀).

🔹 RESTful 하다는 건?

**“RESTful하다”**는 표현은, 위의 REST 원칙을 얼마나 잘 지켜서 구현했는가를 말해요.

예시로 이해해볼게요:

✅ RESTful한 API 예시

동작	HTTP Method	URL	설명
글 목록 조회	GET	`/posts`	전체 글 조회
글 하나 조회	GET	`/posts/1`	ID가 1인 글 조회
글 작성	POST	`/posts`	글 생성
글 수정	PUT	`/posts/1`	ID가 1인 글 전체 수정
글 삭제	DELETE	`/posts/1`	ID가 1인 글 삭제

이처럼 HTTP Method와 URL을 일관되게 사용하는 게 RESTful한 API의 특징이에요.

❌ RESTful하지 않은 API 예시

/getAllPosts, /deletePost?id=1, /createNewPost 등
→ 행위(동사)가 URL에 포함되고 HTTP Method와 역할이 맞지 않음

🔸 요약하면?

REST API: REST 원칙을 따르는 API
RESTful: 그 원칙을 얼마나 잘 지켜서 구현했는가
RESTful한 API는 → 이해하기 쉽고, 일관성 있고, 확장성 높고, 클라이언트-서버가 분리된 구조를 가짐

HATEOAS와 Self-descriptive messages 에 대하여

🔹 Self-descriptive Messages (자체 기술 메시지)

👉 뜻

REST에서 각 요청과 응답은 그 자체만으로 이해될 수 있어야 한다는 원칙이에요.

즉, 서버는 요청을 받고 나서 추가 맥락 없이도 무슨 일을 해야 하는지 알 수 있어야 하고, 클라이언트는 응답만 보고 다음에 무엇을 해야 할지 유추할 수 있어야 해요.

✅ 예시

GET /users/123 HTTP/1.1
Host: api.example.com
Accept: application/json

서버 응답:

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

위 응답은 JSON 포맷으로 되어 있고, 어떤 정보가 담겼는지 명확하게 설명되어 있죠.
즉, “응답만 봐도 내용이 뭔지 알 수 있다” → Self-descriptive 메시지라는 거예요.

🔹 HATEOAS (Hypermedia As The Engine Of Application State)

👉 뜻

REST 시스템에서 클라이언트는 서버로부터 받은 응답의 링크를 통해 다음 행동을 결정해야 한다는 개념이에요.
말이 어려운데, 쉽게 말하면:

“응답 안에 다음에 뭘 할 수 있는지 링크를 줘서, 클라이언트가 직접 경로를 알아내지 않아도 되게 한다.”

✅ 예시 (사용자 조회 응답에 HATEOAS 적용)

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "_links": {
    "self": { "href": "/users/123" },
    "update": { "href": "/users/123", "method": "PUT" },
    "delete": { "href": "/users/123", "method": "DELETE" },
    "posts": { "href": "/users/123/posts" }
  }
}

여기서 _links는 바로 HATEOAS의 핵심이에요.
클라이언트는 이 정보를 보고 “아! 이 사용자에 대해 수정도 가능하고, 글도 볼 수 있네” 라는 걸 API 문서를 몰라도 알 수 있어요.

🔸 요약

개념	설명
Self-descriptive	요청과 응답이 스스로 어떤 의미인지 설명할 수 있어야 함
HATEOAS	응답 안에 다음 행동을 위한 링크/정보가 들어 있어야 함 (하이퍼미디어 중심 설계)

이 둘은 REST 아키텍처의 일관성, 유연성, 확장성을 높이는 데 큰 역할을 해요.
다만 실제 서비스에서는 HATEOAS까지 구현하는 경우는 드물기도 해요. 너무 무거워지기도 하고, 모바일이나 SPA 환경에서는 URL을 클라이언트가 이미 알고 있는 경우가 많거든요.

Restful 한 api를 제공하는 대표 사례

1. GitHub API

설명: GitHub는 개발자들이 코드를 호스팅하고 협업할 수 있는 플랫폼입니다. GitHub의 RESTful API를 통해 리포지토리, 이슈, 사용자 정보 등 다양한 데이터를 조회하고 조작할 수 있습니다.
API 문서: https://docs.github.com/en/rest

2. Twitter API

설명: Twitter는 소셜 네트워크 서비스로, 트윗, 사용자, 해시태그 등의 데이터를 RESTful API를 통해 제공합니다. 이를 통해 트윗 작성, 검색, 사용자 정보 조회 등의 기능을 구현할 수 있습니다.
API 문서: https://developer.twitter.com/en/docs/twitter-api

3. Google Maps API

설명: Google Maps는 지도 서비스로, RESTful API를 통해 지도 이미지, 장소 정보, 경로 안내 등의 기능을 제공합니다. 이를 통해 위치 기반 서비스를 개발할 수 있습니다.
API 문서: https://developers.google.com/maps/documentation

4. Stripe API

설명: Stripe는 온라인 결제 처리 플랫폼으로, RESTful API를 통해 결제, 환불, 구독 관리 등의 기능을 제공합니다. 이를 통해 전자상거래 사이트나 앱에서 결제 시스템을 통합할 수 있습니다.
API 문서: https://stripe.com/docs/api

5. Spotify API

설명: Spotify는 음악 스트리밍 서비스로, RESTful API를 통해 음악 트랙, 앨범, 아티스트 정보 등을 제공합니다. 이를 통해 음악 검색, 재생 목록 관리 등의 기능을 앱에 통합할 수 있습니다.
API 문서: https://developer.spotify.com/documentation/web-api/

6. NASA Open APIs

설명: 미국 항공우주국(NASA)은 다양한 우주 관련 데이터를 RESTful API 형태로 공개하고 있습니다. 예를 들어, Astronomy Picture of the Day(API)를 통해 매일 새로운 우주 사진과 설명을 제공받을 수 있습니다.
API 문서: https://api.nasa.gov/

7. OpenWeatherMap API

설명: OpenWeatherMap은 전 세계 날씨 데이터를 제공하는 서비스로, RESTful API를 통해 현재 날씨, 예보, 과거 날씨 데이터 등을 제공합니다.
API 문서: https://openweathermap.org/api