API 설계와 RESTful 패턴

API란?

API ^{Application Programming Interface}는 소프트웨어 간의 상호작용을 가능하게 하는 인터페이스입니다. API는 다양한 애플리케이션이나 서비스가 데이터를 주고받으며 서로 연동될 수 있도록 도와줍니다. 특히, 현대 웹 애플리케이션에서는 웹 API를 통해 서버와 클라이언트가 데이터를 주고받는 구조가 흔히 사용됩니다. API는 크게 두 가지 방식으로 구분됩니다:

SOAP^{Simple Object Access Protocol}: 주로 XML을 사용해 데이터 교환을 하는 API 방식.
REST^{Representational State Transfer}: HTTP 프로토콜을 활용하여 자원을 정의하고, 이를 CRUD 방식으로 처리하는 아키텍처 패턴. 이 글에서는 RESTful API에 대해 집중적으로 다룹니다.

RESTful API란?

RESTful API는 REST^{Representational State Transfer} 원칙을 따르는 API입니다. REST는 웹에서 자원을 정의하고 이를 상태로 표현한 다음, HTTP 프로토콜을 이용해 자원 간 상호작용을 관리하는 방식입니다. RESTful API는 서버와 클라이언트가 자원^Resource을 주고받을 때, HTTP 메서드를 사용하여 데이터를 관리합니다.

RESTful의 핵심 원칙

RESTful API는 다음과 같은 주요 원칙을 따릅니다:

자원 기반 구조^{Resource-based}: 모든 것이 자원으로 표현됩니다. 예를 들어, 사용자가 자원이면 /users가 자원에 대한 엔드포인트가 됩니다.
HTTP 메서드 사용: RESTful API는 자원에 대한 작업을 HTTP 메서드를 사용해 처리합니다.
- GET: 데이터를 조회할 때 사용.
- POST: 새로운 데이터를 생성할 때 사용.
- PUT: 데이터를 업데이트할 때 사용.
- DELETE: 데이터를 삭제할 때 사용.
무상태성^Stateless) 요청 간의 상태가 서버에 저장되지 않습니다. 즉, 각 요청은 서로 독립적이고, 필요한 모든 정보는 요청 자체에 포함되어야 합니다.
클라이언트-서버 구조: 클라이언트와 서버는 독립적으로 작동하며, 클라이언트는 서버와 상호작용을 위해 명확한 요청을 보냅니다. 서버는 그 요청을 처리하고 응답을 반환합니다.
캐시 가능성^Cacheable: 클라이언트는 응답 데이터를 캐싱할 수 있으며, 이를 통해 성능을 최적화할 수 있습니다.
계층화 시스템^{Layered System}: 클라이언트는 서버와 직접 상호작용하는지 또는 중간 계층을 통해 상호작용 하는지 모릅니다. 이는 시스템의 확장성과 보안성을 높이는 데 도움이 됩니다.

RESTful API 설계 원칙

RESTful API 설계 시 몇 가지 고려해야 할 주요 요소가 있습니다.

자원 URI 설계

RESTful API에서 URI^{Uniform Resource Identifier}는 자원을 식별하는 데 중요한 역할을 합니다. URI는 간결하고, 명확하며, 의미를 잘 전달해야 합니다.

자원의 명사 사용: URI는 동사 대신 명사를 사용해야 합니다. 예를 들어, GET /books는 책 목록을 반환하고, GET /books/123는 특정 ID를 가진 책을 반환하는 URI입니다. 예시:
GET /users: 모든 사용자 정보 조회
POST /users: 새로운 사용자 생성
PUT /users/123: ID 123번 사용자의 정보 업데이트
DELETE /users/123: ID 123번 사용자의 삭제

HTTP 응답 상태 코드

API가 클라이언트 요청에 응답할 때, 각 요청이 성공적으로 처리되었는지, 오류가 발생했는지를 명확히 전달하기 위해 HTTP 상태 코드를 사용합니다.

200 OK: 요청이 성공적으로 처리되었을 때.
201 Created: 새로운 리소스가 성공적으로 생성되었을 때.
400 Bad Request: 잘못된 요청일 때.
401 Unauthorized: 인증이 필요할 때.
404 Not Found: 요청한 리소스를 찾을 수 없을 때.
500 Internal Server Error: 서버에서 예기치 않은 오류가 발생했을 때.

페이징과 필터링

많은 양의 데이터를 제공할 때는 페이징^Paging과 필터링^Filtering 기능을 제공하는 것이 좋습니다. 이를 통해 클라이언트는 원하는 데이터만 효율적으로 요청할 수 있습니다. 예시:

GET /books?author=John: 저자가 John인 책만 필터링.
GET /books?page=2&limit=10: 10개의 항목씩, 2페이지의 책 데이터를 가져옴.

RESTful API 설계 예시

다음은 도서 관리 시스템에 RESTful API를 적용한 예시입니다.

GET /books: 모든 책 목록을 조회하는 API입니다.

GET /books
[
  {
    "id": 1,
    "title": "Clean Code",
    "author": "Robert C. Martin",
    "published": "2008"
  },
  {
    "id": 2,
    "title": "The Pragmatic Programmer",
    "author": "Andrew Hunt",
    "published": "1999"
  }
]

POST /books: 새로운 책을 생성할 때 사용합니다.

POST /books
{
  "title": "Design Patterns",
  "author": "Erich Gamma",
  "published": "1994"
}

PUT /books/1: ID가 1인 책 정보를 업데이트할 때 사용합니다.

PUT /books/1
{
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "published": "2008"
}

DELETE /books/1: ID가 1인 책을 삭제할 때 사용합니다.

RESTful API의 장점

유연성: RESTful API는 다양한 클라이언트와 상호작용할 수 있으며, 확장이 용이합니다. 또한, 웹, 모바일 애플리케이션에서 폭넓게 사용될 수 있습니다.
표준화: HTTP 메서드와 상태 코드를 사용해 일관된 방식으로 데이터를 처리할 수 있습니다.
캐시: 캐시 기능을 활용해 성능을 최적화할 수 있습니다.
확장성: RESTful API는 무상태성을 기반으로 하여 서버와 클라이언트의 부담을 최소화하고, 대규모 트래픽 처리에도 적합합니다.

RESTful API 설계 시 주의 사항

무상태성: 클라이언트는 각 요청마다 필요한 모든 정보를 포함해야 하며, 서버는 요청 간의 상태를 저장하지 않습니다.
보안: 특히 민감한 데이터가 포함된 API의 경우, HTTPS를 사용해 데이터 전송을 암호화하고, 인증 및 권한 부여 메커니즘(JWT, OAuth 등)을 도입하는 것이 필요합니다.
API 문서화: 클라이언트 개발자들이 API를 쉽게 사용할 수 있도록, API 사용법을 명확하게 문서화하는 것이 중요합니다. Swagger나 Postman 등의 도구를 사용해 문서화 및 테스트를 쉽게 할 수 있습니다.

RESTful API와 기타 설계 패턴

GraphQL과 같은 패턴도 REST의 대안으로 자주 언급되며, 특히 클라이언트가 원하는 데이터만을 요청할 수 있도록 유연하게 설계된 것이 특징입니다. 그러나 RESTful API는 여전히 간단하고 널리 사용되는 접근 방식으로 많은 애플리케이션에 적합합니다.

맺음말

RESTful API는 간단하면서도 확장성과 유연성이 뛰어난 웹 서비스 설계 패턴입니다. 자원 기반으로 HTTP 메서드를 활용하여 데이터를 관리하며, 클라이언트와 서버 간의 결합도를 낮추는 것이 특징입니다. RESTful API는 다양한 애플리케이션에서 사용될 수 있으며, 규모에 상관없이 유용하게 적용될 수 있는 설계 방식입니다.

심화 학습

RESTful API는 단순한 CRUD 작업 외에도 더 복잡한 요구사항을 처리하기 위해 다양한 고급 개념들을 포함할 수 있습니다. 여기에서는 RESTful API 설계 시 고려해야 할 몇 가지 심화 주제를 다룹니다.

HATEOAS

HATEOAS^{Hypermedia as the Engine of Application State}는 REST 아키텍처 스타일의 중요한 원칙 중 하나로, 클라이언트가 서버와 상호작용할 때 필요한 모든 정보를 링크를 통해 제공하는 것을 의미합니다. 이는 클라이언트가 서버의 명령이나 하드코딩된 엔드포인트 없이도 상태를 관리할 수 있게 합니다.

예시

{
  "id": 1,
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "links": [
    {
      "rel": "self",
      "href": "/books/1"
    },
    {
      "rel": "borrow",
      "href": "/books/1/borrow"
    },
    {
      "rel": "reviews",
      "href": "/books/1/reviews"
    }
  ]
}

여기서 rel은 리소스 간의 관계를 나타내며, 클라이언트는 해당 링크를 사용하여 특정 동작을 수행하거나 관련 데이터를 조회할 수 있습니다. HATEOAS는 API가 동적으로 확장될 수 있도록 하며, 클라이언트가 하드코딩 없이 필요한 정보를 얻을 수 있게 합니다.

페이징, 정렬, 필터링

RESTful API에서는 한 번에 많은 데이터를 처리하는 것을 방지하기 위해 페이징^Paging, 정렬^Sorting, 필터링^Filtering을 사용하는 것이 중요합니다. 특히 대용량 데이터를 다룰 때 클라이언트가 요청하는 데이터의 양을 제한하고, 원하는 방식으로 데이터를 정렬하거나 필터링할 수 있게 해야 합니다.

예시

페이징: GET /books?page=2&limit=10
정렬: GET /books?sort=title,asc
필터링: GET /books?author=Robert C. Martin 페이징은 서버에서 데이터의 양을 제한해 성능을 최적화할 수 있으며, 클라이언트가 필요한 만큼의 데이터를 받아볼 수 있게 합니다. 필터링은 특정 기준에 맞는 데이터를 클라이언트가 받을 수 있게 하여, 불필요한 데이터 전송을 줄입니다.

버전 관리

API는 시간이 지남에 따라 확장되거나 변경될 수 있으며, 기존 클라이언트와의 호환성을 유지하기 위해 버전 관리^{API Versioning}가 필수적입니다. API 버전 관리를 통해 클라이언트는 적절한 버전의 API에 접근할 수 있으며, 새로운 기능이나 변경 사항이 있을 때 기존 API의 클라이언트에 영향을 주지 않고도 확장이 가능합니다.

버전 관리 방법:

URI 버전 관리: GET /v1/books
헤더를 통한 버전 관리: GET /books (헤더: Accept: application/vnd.api+json;version=1)
쿼리 파라미터를 통한 버전 관리: GET /books?version=1 버전 관리는 API의 안정성과 유연성을 높이는 방법 중 하나이며, 새로운 기능을 추가하면서도 기존 시스템을 보호할 수 있습니다.

Rate Limiting & Throttling

API 사용량이 급격히 증가할 경우 서버에 과부하가 걸릴 수 있습니다. 이를 방지하기 위해 Rate Limiting과 Throttling 기법을 적용해 API 호출 빈도를 제어할 수 있습니다. 이는 특히 공용 API에서 중요한 주제입니다.

예시

Rate Limiting: 사용자가 정해진 시간 안에 특정 횟수 이상 API를 호출하지 못하게 제한하는 방식. 예를 들어, 1000 requests per hour.
Throttling: 사용자의 요청 빈도가 일정 수준을 넘을 경우 요청 처리 속도를 늦추는 방식. 서버는 클라이언트에 요청이 너무 많을 때 429 Too Many Requests 상태 코드를 반환해 요청을 제어할 수 있습니다. 이 방법은 서버의 자원을 보호하고, 공평하게 리소스를 배분하는 데 유용합니다.

보안

RESTful API의 보안^Security은 매우 중요한 주제입니다. 특히, 민감한 데이터가 오가는 시스템에서는 다음과 같은 보안 기법들을 도입할 수 있습니다:

HTTPS: 모든 트래픽을 암호화하기 위해 HTTP 대신 HTTPS를 사용합니다.
인증 및 권한 관리: OAuth, JWT^{JSON Web Token}, API 키 등을 사용하여 API 접근을 제한하고 사용자 권한을 관리합니다.
- OAuth: 외부 애플리케이션이 사용자의 정보를 안전하게 액세스할 수 있도록 도와주는 인증 표준.
- JWT: 클라이언트와 서버 간의 보안된 정보 교환을 위해 사용되는 토큰 기반 인증 방식.

예시: JWT 인증 토큰

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

클라이언트는 이 토큰을 사용하여 이후의 요청에서 권한을 증명할 수 있으며, 서버는 이 토큰을 확인하여 요청을 처리합니다.

이벤트 기반 아키텍처와 웹훅

이벤트 기반 아키텍처는 RESTful API에서 이벤트가 발생할 때 이를 클라이언트에게 실시간으로 전달하는 방식입니다. 웹훅^Webhooks은 클라이언트가 특정 이벤트에 대해 관심을 등록하면, 해당 이벤트가 발생할 때 서버가 클라이언트에게 POST 요청을 보내는 방식으로 실시간 데이터를 제공합니다.

예시

사용자가 책을 대출했을 때, 도서 관리 시스템이 클라이언트 애플리케이션에 알림을 보내는 웹훅 이벤트. 이벤트 기반 아키텍처는 클라이언트가 지속적으로 API를 폴링하는 대신, 이벤트가 발생할 때만 데이터를 받아볼 수 있어 효율적입니다.

GraphQL vs. REST

GraphQL은 REST의 대안으로 등장한 API 설계 방식입니다. REST와 달리, GraphQL은 클라이언트가 원하는 데이터 구조를 자유롭게 요청할 수 있어 유연성이 높습니다. 하지만, GraphQL은 복잡한 쿼리 구조와 더 많은 서버 부하를 초래할 수 있다는 단점도 있습니다. 각 프로젝트의 요구사항에 따라 REST와 GraphQL 중 적합한 방식을 선택하는 것이 중요합니다.

REST vs GraphQL

REST: 명확한 자원 기반, 고정된 응답 구조.
GraphQL: 클라이언트가 요청할 데이터 구조를 자유롭게 지정할 수 있음.

Buy me a coffee

비지니스 로직과 객체지향 설계 비동기 프로그래밍과 객체지향 설계