REST API란?

REST API는 URL의 리소스, 무상태 요청, 표준 HTTP 메서드라는 REST 아키텍처 스타일을 따르는 API입니다. REST(Representational State Transfer, 표현 상태 전송)는 Roy Fielding의 2000년 박사 논문에서 정의되었으며, 프로토콜이나 표준이 아니라 스타일입니다. 함께 지키면 웹 전체가 이미 소비하고 캐시하고 확장하는 법을 아는 API가 만들어지는 제약 조건의 집합입니다.

핵심 요약

순수 HTTP로 보는 전체 CRUD 주기

네 개의 요청에 담긴 스타일 전체입니다. 모든 프레임워크와 SDK가 결국 보내는 것이 바로 이것입니다:

POST /v1/posts                     →  201 Created            생성
{ "title": "Hello REST" }             Location: /v1/posts/8fk2

GET /v1/posts/8fk2                 →  200 OK                 읽기
                                      { "title": "Hello REST", … }

PUT /v1/posts/8fk2                 →  200 OK                 교체
{ "title": "Hello again" }            (PATCH는 필드만 갱신)

DELETE /v1/posts/8fk2              →  204 No Content         삭제
GET /v1/posts/8fk2                 →  404 Not Found          …그리고 사라짐

같은 주기를 REST 호출을 감싼 SDK로 수행한 것입니다:

// JavaScript / Node.js — Back4app JS SDK
// The REST semantics, wrapped: create, read, update, delete
const post = new Parse.Object('Post');
post.set('title', 'Hello REST');
await post.save();                            // POST   /classes/Post      → 201

const fetched = await new Parse.Query('Post')
  .get(post.id);                              // GET    /classes/Post/:id  → 200

fetched.set('title', 'Hello again');
await fetched.save();                         // PUT    /classes/Post/:id  → 200

await fetched.destroy();                      // DELETE /classes/Post/:id  → 200

// Flutter / Dart — Back4app Flutter SDK
// The REST semantics, wrapped: create, read, update, delete
final post = ParseObject('Post')..set('title', 'Hello REST');
await post.save();          // POST   /classes/Post      → 201

await post.fetch();         // GET    /classes/Post/:id  → 200

post.set('title', 'Hello again');
await post.save();          // PUT    /classes/Post/:id  → 200

await post.delete();        // DELETE /classes/Post/:id  → 200

// iOS / Swift — Back4app Swift SDK
// The REST semantics, wrapped: create, read, update, delete
var post = Post()
post.title = "Hello REST"
let saved = try await post.save()      // POST   /classes/Post      → 201

let fetched = try await saved.fetch()  // GET    /classes/Post/:id  → 200

var updated = fetched
updated.title = "Hello again"
_ = try await updated.save()           // PUT    /classes/Post/:id  → 200

try await updated.delete()             // DELETE /classes/Post/:id  → 200

// Android / Kotlin — Back4app Android SDK
// The REST semantics, wrapped: create, read, update, delete
val post = ParseObject("Post")
post.put("title", "Hello REST")
post.save()                                    // POST   /classes/Post      → 201

val fetched = ParseQuery.getQuery<ParseObject>("Post")
    .get(post.objectId)                        // GET    /classes/Post/:id  → 200

fetched.put("title", "Hello again")
fetched.save()                                 // PUT    /classes/Post/:id  → 200

fetched.delete()                               // DELETE /classes/Post/:id  → 200

REST의 여섯 가지 제약 조건

1. 클라이언트-서버 – 인터페이스와 구현이 독립적으로 진화합니다. UI는 스토리지가 어떻게 동작하는지 결코 알지 못합니다.
2. 무상태 – 모든 요청은 자기 완결적입니다. 서버는 호출 사이에 세션을 유지하지 않으며, 이것이 어떤 복제본이든 어떤 요청에든 응답할 수 있게 합니다.
3. 캐시 가능 – 응답은 자신의 캐시 가능성을 스스로 선언합니다. 적절한 캐시 헤더를 가진 GET은 웹의 캐싱 인프라 전체(브라우저, CDN, 프록시)가 API를 위해 일하게 합니다.
4. 균일한 인터페이스 – REST 그 자체인 제약 조건으로, 네 부분으로 이루어집니다. URI로 식별되는 리소스, 표현을 통한 조작(리소스가 되기를 바라는 JSON을 돌려보냄), 자기 서술적 메시지(메서드 + 헤더가 요청 처리에 필요한 모든 것을 말함), 그리고 애플리케이션 상태의 엔진으로서의 하이퍼미디어(응답이 다음 동작으로 링크함)입니다.
5. 계층화된 시스템 – 클라이언트는 자신이 오리진 서버, 캐시, 게이트웨이 중 무엇과 대화하는지 알 수 없습니다. 중개자가 자유롭게 끼어듭니다.
6. 주문형 코드 (선택) – 서버가 실행 가능한 코드를 클라이언트에 보낼 수 있습니다. 선택 사항으로 표시된 유일한 제약 조건이며, 대부분의 API가 무시하는 제약 조건입니다.

HTTP 메서드: 안전성, 멱등성, CRUD

거의 모든 상위 노출 페이지에 빠져 있는 표입니다. RFC 9110의 의미론을 압축했습니다:

안전하다는 것은 요청이 아무것도 바꾸지 않는다는 뜻이고, 멱등하다는 것은 반복해도 더 이상 바뀌지 않는다는 뜻입니다. 이는 잡학이 아니라 재시도 정책 그 자체입니다. PUT에서의 네트워크 타임아웃은 두려움 없이 재시도할 수 있지만, POST에서의 같은 타임아웃에는 멱등성 키나 중복 검사가 필요합니다. 전체 CRUD 매핑은 별도 항목에서 다룹니다.

상태 코드: 언제 무엇을 반환할까

401/403과 200/201/204의 구분은 API 장인 정신이 드러나는 지점입니다. 정확한 코드는 상태 줄만으로 클라이언트를 디버깅할 수 있게 합니다.

이 API는 정말 REST인가? 성숙도 사다리

상업적 설명 글이 빠뜨리는 솔직한 섹션입니다. Richardson 성숙도 모델은 HTTP API를 등급으로 나눕니다. 0단계(URL 하나, 동사 하나, 변장한 RPC), 1단계(URL의 리소스), 2단계(올바른 메서드와 상태 코드), 3단계(하이퍼미디어, HATEOAS)입니다.

Fielding 본인의 주장에 따르면 하이퍼미디어 없는 API는 REST가 아니며, 그는 정확히 그렇게 말하는 날 선 글을 썼습니다. 실제로는 찬사를 받는 거의 모든 “REST API”가 2단계 HTTP API입니다. 리소스, 동사, 상태 코드, JSON, 하이퍼미디어 없음. 이는 순수성보다 어휘의 문제로서 중요합니다. 사다리를 알면 채용 공고(2단계)와 박사 논문(3단계)에서 이 용어가 각각 무엇을 뜻하는지 알 수 있고, 맹목적인 HATEOAS 숭배와 현학적인 지적 양쪽을 피할 수 있습니다.

REST vs. SOAP vs. GraphQL vs. gRPC

GraphQL 비교는 별도 항목에서 다룹니다.

REST API를 쾌적하게 만드는 관례

제약 조건 너머에, 소비자가 말없이 점수를 매기는 관례가 있습니다. 복수형 명사 리소스(/getPost가 아니라 /posts), 중첩은 최대 한 단계(/posts/8fk2/comments까지만), 모든 컬렉션에 페이지네이션(깊이와 안정성을 위한 커서 기반, 상한 강제), 쿼리 파라미터로 하는 필터링과 정렬(엔드포인트 변형이 아니라), 명시적 정책이 있는 버전 관리(/v1/ 경로 또는 헤더 중 하나를 고르고 지원 중단 기간을 공표), 콘텐츠 협상 준수(Accept, Content-Type), 그리고 산문이 아니라 기계가 읽을 수 있는 코드를 담은 구조화된 JSON 오류입니다. 이 중 어느 것도 박사 논문에는 없지만, 개발자가 추천하는 API와 억지로 참고 쓰는 API의 차이는 전부 여기에 있습니다.

일반적인 사용 사례

• 공개 및 파트너 API – REST의 보편성이 곧 기능입니다. 모든 언어, 도구, 개발자가 REST를 말합니다.
• 모바일과 웹 앱 백엔드 – HTTP 위의 리소스 CRUD는 대부분의 앱 화면이 실제로 데이터를 소비하는 방식과 맞아떨어집니다.
• 마이크로서비스 이음새 – HTTP 도구(게이트웨이, 추적, 캐싱)가 제값을 하는 내부 계약.
• 웹훅 방식 연동 – 양쪽이 이미 이해하는 평범한 HTTP 호출로 시스템이 시스템에 알리는 방식.
• 자동 생성 데이터 API – 데이터베이스를 REST 리소스로 노출하는 플랫폼. 스키마에서 동작하는 API까지 가장 빠른 경로입니다.

REST를 사용해야 할까? 결정 매트릭스

한계와 트레이드오프

• 고정된 표현은 다양한 클라이언트에 맞지 않습니다. 오버/언더페칭 쌍은 REST의 구조적 약점입니다. 희소 필드 집합과 확장 파라미터가 완화하고, GraphQL은 다시 설계합니다.
• 필수 계약이 없습니다. OpenAPI 명세를 강제하는 것은 없으므로 많은 REST API가 구전으로 문서화됩니다. gRPC와 GraphQL이 구조적으로 강제하는 규율이 여기서는 선택 사항입니다.
• 무상태는 컨텍스트를 반복합니다. 인증과 테넌트 컨텍스트가 모든 요청에 실립니다. 바이트로는 저렴하지만 세션 의미론을 토큰으로 밀어내고 일부 흐름(다단계 트랜잭션)을 어색하게 만듭니다.
• 설계상 N+1의 유혹. URL당 리소스라는 사고방식은 항목마다 한 번씩 호출하는 클라이언트를 부릅니다. 좋은 API는 소비자가 루프를 즉석에서 만들기 전에 확장과 배칭 기능을 제공합니다.
• “REST”라는 단어는 모호합니다. 대부분의 사람에게는 2단계 HTTP API이고 박사 논문에서는 하이퍼미디어 아키텍처입니다. 명세, 채용 공고, 리뷰어가 어느 쪽을 뜻하는지 읽고 나서 논쟁해야 합니다.

Back4app에서의 REST API

Back4app은 관리형 데이터베이스, 자동 생성되는 REST 및 GraphQL API, 인증, 파일 스토리지, Cloud Code 서버리스 함수를 결합한 오픈소스 Backend as a Service(BaaS) 플랫폼입니다. 여기서 REST API는 구축되는 것이 아니라 생성됩니다. 데이터 모델의 모든 클래스가 즉시 리소스가 됩니다. POST /classes/Post가 생성하고 GET /classes/Post/:id가 읽으며, 위 안내에서 본 메서드, 상태 코드, Location 의미론을 그대로 갖추고, 키, 사용자 토큰, 클래스 수준 권한이 경계를 지킵니다. 코드 탭은 같은 주기를 SDK로 보여 주는데, SDK는 정확히 이 HTTP 위의 얇은 관용적 래퍼입니다. 작업이 CRUD를 넘어서면 Cloud Code 함수가 파일 하나로 커스텀 엔드포인트를 추가합니다. 기본적으로 올바른 2단계 REST를, 클래스를 정의하는 시간 안에 스키마에서 URL까지 얻습니다.