catsridingCATSRIDING|OCEANWAVES
Dev

REST API URL 설계하기

jynn@catsriding.com
Nov 14, 2023
Published byJynn
999
REST API URL 설계하기

Naming Conventions for REST API

REST API의 URI는 자원(Resource)과 행위(Operation)을 식별하여 계층구조로 일관되고 명확하게 설계하는 것이 좋습니다. 반드시 지켜야 하는 규칙이 있는 것은 아니지만 REST 서비스를 위한 가이드라인이 있습니다.

REST API는 클라이언트와 서버 간의 중요한 인터페이스 역할을 합니다. 명확한 네이밍 컨벤션은 API의 이해와 활용을 쉽게 하여 개발자와 사용자가 더 효율적으로 작업할 수 있게 합니다. 일관된 네이밍 규칙은 팀 내 협업을 원활하게 하고, API 동작의 예측 가능성을 높이며, 견고하고 확장 가능한 아키텍처를 구축하는 데 기여합니다.

Principles of REST API URL Design

REST API URL 설계에는 몇 가지 핵심 원칙이 있습니다. 이러한 원칙들은 API를 명확하고 일관성 있게 유지하는 데 도움이 됩니다.

Identifying Resources with Nouns

자원(Resource)을 식별할 때는 복수형 명사(Plural Nouns)를 사용합니다. 자원은 일반적으로 데이터베이스의 엔터티나 비즈니스 도메인 객체를 나타내며, 명사는 이러한 자원을 명확하게 식별하는 데 사용됩니다. 이는 URL을 이해하기 쉽게 하고, API의 목적을 명확하게 전달합니다.

REST API에서 리소스를 복수형으로 사용하는 이유는 자원 컬렉션을 명확히 나타내어 엔드포인트가 여러 리소스를 다룬다는 것을 직관적으로 이해할 수 있게 합니다. 예를 들어, /users 엔드포인트는 사용자 목록을, /users/{userId} 엔드포인트는 특정 사용자를 나타냅니다. 이렇게 하면 API 구조가 일관되고 예측 가능해져, 개발자와 사용자 모두에게 더 나은 사용성을 제공합니다. 또한, 이는 REST 아키텍처의 원칙을 준수하여 명확하고 체계적인 API 설계를 지원합니다.

  • 사용자 목록 조회 API:
GET /users HTTP/1.1
Host: api.catsriding.app
  • 상품 목록 조회 API:
GET /products HTTP/1.1
Host: api.catsriding.app

Defining Operations with HTTP Methods

행위(Operations)는 HTTP 메서드를 통해 정의합니다. HTTP 메서드는 자원을 조작하는 방법을 명확히 구분할 수 있게 합니다. 각 메서드는 특정한 목적을 가지며, 이를 통해 API 사용자는 자원에 대해 어떤 작업이 수행될지 쉽게 이해할 수 있습니다.

HTTP 메서드에는 다음과 같은 종류가 있습니다:

  • GET: 자원을 조회합니다. 주로 요청 바디를 가지지 않으며, URL 경로와 쿼리 파라미터로 자원을 식별합니다.
  • POST: 자원을 생성합니다. 요청 바디에 새로 생성될 자원의 정보를 담아 서버에 보냅니다.
  • PUT 또는 PATCH: 자원을 수정합니다. PUT은 자원의 전체를 업데이트하는 데 사용되며, PATCH는 자원의 일부를 업데이트하는 데 사용됩니다. 두 메서드 모두 요청 바디에 수정할 데이터를 포함합니다.
  • DELETE: 자원을 삭제합니다. 주로 요청 바디를 가지지 않으며, URL 경로로 삭제할 자원을 식별합니다.

일반적으로 GET 및 DELETE 메서드는 요청 바디를 가지지 않으며, 데이터를 수정하는 POST, PUT 그리고 PATCH 메서드는 요청 바디를 포함합니다. 일부 상황에서는 GET 메서드에 바디를 포함시키거나, POST 메서드를 사용하여 자원을 조회하도록 API를 설계할 수도 있지만, 이는 표준적인 사용법이 아니므로 혼동을 피하기 위해 지양해야 합니다. 원활한 협업과 소통을 위해서 컨벤션을 지키는 것이 중요합니다.

아래는 다양한 HTTP 메서드를 활용한 구체적인 API 예시입니다.

  • 특정 사용자 조회 API:
GET /users/{userId} HTTP/1.1
Host: api.catsriding.app
  • 새로운 사용자 등록 API:
POST /users HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "name": "ongs",
    "email": "ongs@catsriding.com"
}
  • 사용자 정보 수정 API:
PUT /users/{userId} HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "name": "mongs",
    "email": "mongs@catsriding.com"
}
  • 특정 사용자 삭제 API:
DELETE /users/{userId} HTTP/1.1
Host: api.catsriding.app

API Versioning

API를 버전 관리하는 방법은 여러 가지가 있지만, 가장 일반적인 방법은 URL에 버전을 포함시키는 것입니다. 이는 하위 호환성을 유지하면서 새로운 기능을 추가하거나 기존 기능을 변경할 수 있게 합니다. 버전 관리는 특히 큰 변경 사항이 있을 때 유용합니다.

로그인 API의 버전 관리 예시는 다음과 같습니다:

  • 로그인 API v1:
POST /v1/login HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "username": "ongs",
    "password": "pass"
}
  • 로그인 API v2:
POST /v2/login HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "username": "ongs",
    "password": "pass",
    "otp": "123456"
}

Practical Examples

다음은 위의 원칙들을 적용한 REST API URL 설계 예시입니다. 이러한 예시들은 API의 사용자가 URI만 보고도 그 기능을 쉽게 이해할 수 있도록 합니다.

Products API

상품 관련 API는 상품의 목록 조회, 특정 상품 조회, 새로운 상품 추가, 상품 정보 수정, 상품 삭제 등 다양한 기능을 포함합니다.

  • 상품 목록을 조회하는 API:
GET /products HTTP/1.1
Host: api.catsriding.app
  • 특정 상품을 조회하는 API:
GET /products/{productId} HTTP/1.1
Host: api.catsriding.app
  • 새로운 상품을 추가하는 API:
POST /products HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "name": "New Product",
    "price": 29.99
}
  • 특정 상품 정보를 수정하는 API:
PUT /products/{productId} HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "name": "Updated Product",
    "price": 39.99
}
  • 특정 상품을 삭제하는 API:
DELETE /products/{productId} HTTP/1.1
Host: api.catsriding.app

Orders API

주문 관련 API는 주문의 목록 조회, 특정 주문 조회, 새로운 주문 추가, 주문 정보 수정, 주문 삭제 등을 포함합니다.

  • 주문 목록을 조회하는 API:
GET /orders HTTP/1.1
Host: api.catsriding.app
  • 특정 주문을 조회하는 API:
GET /orders/{orderId} HTTP/1.1
Host: api.catsriding.app
  • 새로운 주문을 추가하는 API:
POST /orders HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "productId": 123,
    "quantity": 2
}
  • 특정 주문 정보를 수정하는 API:
PATCH /orders/{orderId} HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "quantity": 3
}
  • 특정 주문을 삭제하는 API:
DELETE /orders/{orderId} HTTP/1.1
Host: api.catsriding.app

Reviews API

리뷰 관련 API는 리뷰의 목록 조회, 특정 리뷰 조회, 새로운 리뷰 추가, 리뷰 정보 수정, 리뷰 삭제 등을 포함합니다.

  • 리뷰 목록을 조회하는 API:
GET /reviews HTTP/1.1
Host: api.catsriding.app
  • 특정 리뷰를 조회하는 API:
GET /reviews/{reviewId} HTTP/1.1
Host: api.catsriding.app
  • 새로운 리뷰를 추가하는 API:
POST /reviews HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "productId": 123,
    "userId": 456,
    "rating": 5,
    "comment": "Great product!"
}
  • 특정 리뷰 정보를 수정하는 API:
PATCH /reviews/{reviewId} HTTP/1.1
Host: api.catsriding.app
Content-Type: application/json

{
    "rating": 4,
    "comment": "Updated review"
}
  • 특정 리뷰를 삭제하는 API:
DELETE /reviews/{reviewId} HTTP/1.1
Host: api.catsriding.app

Structure Brings Freedom

REST API URL 설계는 단순한 규칙 이상의 의미를 가지며, API의 성공적인 운영과 유지보수를 위한 중요한 요소입니다. 명확하고 일관된 네이밍 컨벤션을 통해 팀 내 협업을 원활히 하고, API 사용자들에게 직관적인 인터페이스를 제공할 수 있습니다. 이처럼 컨벤션을 지키는 것은 개발에서 매우 중요합니다. 명확한 규칙과 구조는 개발자들이 효율적으로 작업할 수 있게 하여, 비즈니스 로직에 더 집중할 수 있게 합니다.

  • Protocol
  • Web