REST API: 두 판 사이의 차이

기술노트
편집 요약 없음
(Gemini 벌크 업로더로 자동 업로드)
 
1번째 줄: 1번째 줄:
== 🔍 REST API란? ==
== REST API ==


'''REST API'''는 "Representational State Transfer" 원칙을 기반으로 만들어진 웹 API입니다.  
'''REST(Representational State Transfer)'''는 분산 하이퍼미디어 시스템을 위한 '''아키텍처 스타일'''입니다. 웹의 기존 기술과 HTTP 프로토콜을 최대한 활용하여 확장성, 단순성, 신뢰성 등을 높이는 것을 목표로 합니다. '''REST API'''는 이러한 REST 아키텍처 스타일의 제약 조건을 따르는 API를 의미합니다.
웹의 자원을 URI로 표현하고, HTTP 메서드를 통해 자원에 대한 동작(조회, 생성, 수정, 삭제 등)을 수행합니다.


=== 🌐 REST란? ===
----


* REST는 2000년 로이 필딩(Roy Fielding)이 논문에서 제안한 '''웹 아키텍처 설계 원칙'''입니다.
=== 🏛️ REST의 6가지 제약 조건 ===
* HTTP 프로토콜을 기반으로, 자원을 URI로 표현하고, 상태 전이(transfer)를 통해 자원을 조작하는 방식입니다.
* REST는 다음과 같은 6가지 제약 조건을 따릅니다:
# '''클라이언트-서버 구조''' – 클라이언트와 서버의 책임을 명확히 분리하여 역할 독립성과 확장성을 확보합니다.
# '''무상태성 (Stateless)''' – 요청 간 서버에 클라이언트 상태를 저장하지 않으며, 모든 요청은 독립적으로 처리됩니다.
# '''캐시 처리 가능''' – 응답에 캐시 가능 여부를 명시하여 클라이언트가 데이터를 효율적으로 재사용할 수 있습니다.
# '''계층화된 시스템''' – 클라이언트는 중간 계층(프록시, 게이트웨이 등)을 통해 서버에 접근할 수 있으며, 각 계층은 독립적으로 동작합니다.
# '''인터페이스 일관성 (Uniform Interface)''' – 모든 리소스는 일관된 방식(URI, HTTP 메서드 등)으로 접근되어야 하며, REST의 핵심 특징입니다.
# '''코드 온 디맨드 (선택적)''' – 클라이언트는 서버로부터 실행 가능한 코드를 전송받아 동적으로 기능을 확장할 수 있습니다 (예: JavaScript).


1.  '''클라이언트-서버 (Client-Server)''' : 클라이언트와 서버의 역할이 명확히 분리되어 각각 독립적으로 발전할 수 있습니다.
2.  '''무상태성 (Stateless)''' : 서버는 클라이언트의 요청 간에 어떤 클라이언트 상태도 저장하지 않습니다. 각 요청은 필요한 모든 정보를 포함해야 합니다. (장점: 서버 확장성 용이, 서버 부담 감소)
3.  '''캐시 가능 (Cacheable)''' : 클라이언트는 응답을 캐시할 수 있어야 하며, 서버는 응답이 캐시 가능한지 명시해야 합니다. (장점: 응답 시간 단축, 서버 부하 감소)
4.  '''계층화된 시스템 (Layered System)''' : 클라이언트는 서버와 직접 통신하는지, 중간에 프록시, 로드 밸런서, 게이트웨이 등이 있는지 알 필요가 없습니다.
5.  '''코드 온 디맨드 (Code-On-Demand, Optional)''' : 서버가 클라이언트에 실행 가능한 코드(e.g., JavaScript)를 전송하여 클라이언트 기능을 확장할 수 있습니다. (선택 사항)
6.  '''인터페이스 일관성 (Uniform Interface)''' : REST의 핵심. 시스템 전체에 걸쳐 일관된 인터페이스를 제공합니다.
> * '''자원의 식별''' : URI(Uniform Resource Identifier)를 사용하여 리소스를 식별합니다. (e.g., `/users/1`, `/products`)
> * '''메시지를 통한 리소스 조작''' : HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 리소스를 조작합니다.
> * '''자기 서술적 메시지''' : 메시지 자체에 필요한 모든 정보(미디어 타입, 상태 코드 등)를 포함하여 메시지만으로 이해 가능해야 합니다.
> * '''하이퍼미디어 (HATEOAS, Hypermedia As The Engine Of Application State)''' : 응답에 다음 가능한 상태 전이를 위한 링크를 포함합니다. (REST의 이상적인 형태)


=== 🧱 REST API의 구성 요소 ===
----


* '''자원(Resource)''': URI로 식별되는 객체 (예: <code>/users</code>, <code>/posts/1</code>)
=== 🛠️ REST API 설계 원칙 ===
* '''메서드(Method)''': HTTP 메서드를 통해 자원에 대한 행위 지정
* '''표현(Representation)''': 자원의 데이터 형식 (JSON, XML 등)
* '''상태 코드(Status Code)''': 요청 처리 결과를 나타냄


=== 📌 HTTP 메서드 매핑 ===
*  '''URI는 리소스를 표현해야 한다''' : 동사보다는 명사를 사용하고, 복수형을 사용하는 것이 일반적입니다. (e.g., `/users` 대신 `/user`, `/getUser` 대신 `/users`)
*  '''HTTP 메서드로 행위(CRUD)를 표현한다'''
> * `GET`: 리소스 조회 (멱등성, Idempotent)
> * `POST`: 리소스 생성 (멱등성 X)
> * `PUT`: 리소스 전체 수정 (멱등성)
> * `PATCH`: 리소스 부분 수정 (멱등성 X)
> * `DELETE`: 리소스 삭제 (멱등성)
*  '''메시지는 자기 서술적이어야 한다''' : HTTP 헤더(Content-Type, Accept 등)와 상태 코드(Status Code)를 적절히 사용하여 메시지 자체로 의미를 전달해야 합니다.


{| class="wikitable"
----
|+ '''REST API에서의 HTTP 메서드 사용'''
! 메서드 !! 의미 !! 예시
|-
| GET || 리소스 조회 || <code>GET /users/1</code>
|-
| POST || 리소스 생성 || <code>POST /users</code>
|-
| PUT || 리소스 전체 수정 || <code>PUT /users/1</code>
|-
| PATCH || 리소스 일부 수정 || <code>PATCH /users/1</code>
|-
| DELETE || 리소스 삭제 || <code>DELETE /users/1</code>
|}


=== ✅ REST API의 장점 ===
=== 💡 개발자 핵심 Point ===


* URI와 HTTP 메서드만으로도 의미가 명확하여 '''가독성'''과 '''일관성'''이 좋음
* REST API는 웹 서비스 개발의 사실상 표준으로 자리 잡았습니다.
* '''표준 HTTP 기능 활용''' (캐시, 상태 코드 등)
* '''RESTful 하다''' : REST의 제약 조건을 잘 지키는 API를 'RESTful 하다'고 표현합니다. 특히 '인터페이스 일관성'과 '무상태성'이 중요합니다.
* '''클라이언트와 서버의 역할 분리''' 가능
* '''HATEOAS의 중요성''' : REST의 가장 이상적인 형태이지만, 실제 구현에서는 복잡성 때문에 완전히 지켜지지 않는 경우가 많습니다. 하지만 REST의 철학을 이해하는 데 중요합니다.
* 확장성과 유지보수가 뛰어남
* '''API 버전 관리''' : API가 변경될 경우, 기존 클라이언트와의 호환성을 위해 버전 관리가 필요합니다. (e.g., URI에 버전 포함 `/v1/users`, 헤더에 버전 포함)
 
* '''API 문서화''' : REST API는 자기 서술적이어야 하지만, 복잡한 비즈니스 로직이나 사용법을 명확히 전달하기 위해 Swagger/OpenAPI와 같은 도구를 사용하여 API 문서를 잘 작성하는 것이 중요합니다.
=== ⚠️ REST API 주의사항 ===
 
* URI에는 '''동사 대신 명사'''를 사용해야 함 (예: <code>/users</code> OK, <code>/getUser</code>는 지양)
* 자원의 관계를 '''계층 구조 URI'''로 표현 (예: <code>/posts/10/comments</code>)
* 메서드의 의미와 일치하는 동작을 구현해야 함 (예: 삭제는 DELETE로 처리)
 
=== 📘 예시: 사용자 API ===
 
{| class="wikitable"
|+ '''REST API 설계 예시: 사용자(User)'''
! 동작 !! URI !! 메서드
|-
| 사용자 목록 조회 || <code>/users</code> || GET
|-
| 사용자 등록 || <code>/users</code> || POST
|-
| 특정 사용자 조회 || <code>/users/1</code> || GET
|-
| 사용자 정보 수정 || <code>/users/1</code> || PUT 또는 PATCH
|-
| 사용자 삭제 || <code>/users/1</code> || DELETE
|}

2025년 9월 11일 (목) 16:50 기준 최신판

REST API

REST(Representational State Transfer)는 분산 하이퍼미디어 시스템을 위한 아키텍처 스타일입니다. 웹의 기존 기술과 HTTP 프로토콜을 최대한 활용하여 확장성, 단순성, 신뢰성 등을 높이는 것을 목표로 합니다. REST API는 이러한 REST 아키텍처 스타일의 제약 조건을 따르는 API를 의미합니다.

🏛️ REST의 6가지 제약 조건

1. 클라이언트-서버 (Client-Server) : 클라이언트와 서버의 역할이 명확히 분리되어 각각 독립적으로 발전할 수 있습니다. 2. 무상태성 (Stateless) : 서버는 클라이언트의 요청 간에 어떤 클라이언트 상태도 저장하지 않습니다. 각 요청은 필요한 모든 정보를 포함해야 합니다. (장점: 서버 확장성 용이, 서버 부담 감소) 3. 캐시 가능 (Cacheable) : 클라이언트는 응답을 캐시할 수 있어야 하며, 서버는 응답이 캐시 가능한지 명시해야 합니다. (장점: 응답 시간 단축, 서버 부하 감소) 4. 계층화된 시스템 (Layered System) : 클라이언트는 서버와 직접 통신하는지, 중간에 프록시, 로드 밸런서, 게이트웨이 등이 있는지 알 필요가 없습니다. 5. 코드 온 디맨드 (Code-On-Demand, Optional) : 서버가 클라이언트에 실행 가능한 코드(e.g., JavaScript)를 전송하여 클라이언트 기능을 확장할 수 있습니다. (선택 사항) 6. 인터페이스 일관성 (Uniform Interface) : REST의 핵심. 시스템 전체에 걸쳐 일관된 인터페이스를 제공합니다. > * 자원의 식별 : URI(Uniform Resource Identifier)를 사용하여 리소스를 식별합니다. (e.g., `/users/1`, `/products`) > * 메시지를 통한 리소스 조작 : HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용하여 리소스를 조작합니다. > * 자기 서술적 메시지 : 메시지 자체에 필요한 모든 정보(미디어 타입, 상태 코드 등)를 포함하여 메시지만으로 이해 가능해야 합니다. > * 하이퍼미디어 (HATEOAS, Hypermedia As The Engine Of Application State) : 응답에 다음 가능한 상태 전이를 위한 링크를 포함합니다. (REST의 이상적인 형태)

🛠️ REST API 설계 원칙

  • URI는 리소스를 표현해야 한다 : 동사보다는 명사를 사용하고, 복수형을 사용하는 것이 일반적입니다. (e.g., `/users` 대신 `/user`, `/getUser` 대신 `/users`)
  • HTTP 메서드로 행위(CRUD)를 표현한다

> * `GET`: 리소스 조회 (멱등성, Idempotent) > * `POST`: 리소스 생성 (멱등성 X) > * `PUT`: 리소스 전체 수정 (멱등성) > * `PATCH`: 리소스 부분 수정 (멱등성 X) > * `DELETE`: 리소스 삭제 (멱등성)

  • 메시지는 자기 서술적이어야 한다 : HTTP 헤더(Content-Type, Accept 등)와 상태 코드(Status Code)를 적절히 사용하여 메시지 자체로 의미를 전달해야 합니다.

💡 개발자 핵심 Point

  • REST API는 웹 서비스 개발의 사실상 표준으로 자리 잡았습니다.
  • RESTful 하다 : REST의 제약 조건을 잘 지키는 API를 'RESTful 하다'고 표현합니다. 특히 '인터페이스 일관성'과 '무상태성'이 중요합니다.
  • HATEOAS의 중요성 : REST의 가장 이상적인 형태이지만, 실제 구현에서는 복잡성 때문에 완전히 지켜지지 않는 경우가 많습니다. 하지만 REST의 철학을 이해하는 데 중요합니다.
  • API 버전 관리 : API가 변경될 경우, 기존 클라이언트와의 호환성을 위해 버전 관리가 필요합니다. (e.g., URI에 버전 포함 `/v1/users`, 헤더에 버전 포함)
  • API 문서화 : REST API는 자기 서술적이어야 하지만, 복잡한 비즈니스 로직이나 사용법을 명확히 전달하기 위해 Swagger/OpenAPI와 같은 도구를 사용하여 API 문서를 잘 작성하는 것이 중요합니다.
원본 주소 "https://technote.wiki/index.php?title=REST_API&oldid=1055"