RESTful API를 효과적으로 설계하는 것은 확장 가능하고 유지 관리가 가능하며 사용하기 쉬운 시스템을 만드는 데 중요합니다. 특정 표준이 존재하지만 대부분은 엄격한 규칙이 아니라 API 설계를 안내하는 모범 사례입니다. API에 널리 사용되는 아키텍처 패턴 중 하나는 MVC(Model-View-Controller)이지만 그것만으로는 이름 지정 및 구조와 같은 API 디자인의 더 미세한 측면을 다루지 않습니다. 이 글에서는 REST API 구성을 위한 필수 지침을 살펴보겠습니다.

1. 명명 규칙 및 리소스 중심 설계 API는 종종 "사용자", "제품" 또는 "주문"과 같은 시스템의 엔터티를 나타내는 리소스를 중심으로 정의됩니다. 리소스는 단일 항목 또는 컬렉션일 수 있으며 API는 이러한 리소스와 상호 작용할 수 있는 직관적이고 명확한 방법을 제공해야 합니다.

주요 원칙:
리소스 지향: 작업이 아닌 리소스를 중심으로 API를 설계합니다. 자원은 동사가 아닌 명사로 생각되어야 합니다. 예를 들어:

/users 사용자 컬렉션에 액세스합니다.
/users/{userId} - 특정 사용자에 액세스합니다.
일관성: API는 직관적이어야 합니다. 사용자가 /users에서 리소스 목록을 가져올 수 있는 경우 식별자: /users/{userId}.

컬렉션과 단일 리소스 비교:

리소스 모음은 복수 명사(/users, /products)로 표현됩니다.
단일 리소스는 해당 리소스의 고유 식별자(/users/{userId}, /products/{productId}.

1. HTTP 메서드는 URI가 아닌 작업을 정의합니다. 수행 중인 작업(데이터 검색, 새 항목 생성, 기존 데이터 업데이트 등)은 URI에 포함되어서는 안 됩니다. 대신 HTTP 메서드가 작업을 결정합니다.

일반적인 HTTP 메서드 및 사용 사례:
GET: 서버에서 데이터를 검색합니다.

예: GET /products는 모든 제품 목록을 반환합니다.
예: GET /users/{userId}는 지정된 userId를 가진 사용자를 검색합니다.
POST: 서버에 새 리소스를 생성합니다.

예: POST /users가 새 사용자를 생성합니다.
PUT: 기존 리소스를 새 데이터로 교체합니다(전체 업데이트).

예: PUT /users/{userId}는 사용자의 데이터를 완전히 새로운 데이터로 바꿉니다.
패치: 기존 리소스를 부분적으로 업데이트합니다(부분 업데이트).

예: PATCH /users/{userId}는 전화번호와 같은 지정된 속성만 업데이트합니다.
DELETE: 리소스를 삭제합니다.

예: DELETE /users/{userId}는 지정된 userId를 가진 사용자를 삭제합니다.

1. REST의 무국적자 REST API는 상태 비저장이어야 합니다. 즉, 모든 API 호출에는 서버가 요청을 처리하는 데 필요한 모든 정보가 포함되어야 합니다. 이렇게 하면 각 요청이 자급자족하고 이전 요청에 종속되지 않습니다.

예: 사용자 세부정보를 가져오기 위해 GET 요청을 할 때 이전 요청에서 이미 사용자를 인증했더라도 요청에는 필수 인증 토큰이 포함되어야 합니다. 이는 서로 다른 요청이 서로 다른 서버에 도달할 수 있는 분산 시스템에서 필수적입니다.

1. 서버별 데이터 저장 방지 단일 API 요청은 특정 서버에 임시 데이터를 저장하는 데 의존해서는 안 됩니다. 분산 시스템에서는 들어오는 요청이 임의의 서버로 라우팅될 수 있으므로 어떤 서버가 요청을 처리하는지에 관계없이 동일한 결과를 얻어야 합니다. 이것이 바로 세션 상태를 개별 서버에 저장해서는 안 되는 이유입니다.

해결책: 세션 관리를 위해 Redis와 같은 중앙 집중식 또는 분산형 스토리지 시스템이나 JWT(JSON Web Token)와 같은 상태 비저장 인증 메커니즘을 사용하세요.

1. 리소스 테이블과 데이터베이스 테이블 API 디자인에는 데이터베이스 테이블과 API 엔드포인트 간의 일대일 매핑이 있어서는 안 됩니다. API는 여러 테이블이나 소스의 데이터를 결합할 수 있는 논리적이고 의미 있는 리소스를 노출해야 합니다.

예:
GET /orders/{orderId}는 주문, order_items 및 고객 테이블의 정보를 결합하여 주문 세부 정보를 검색할 수 있습니다.

1. 데이터 유형의 유연성 REST API는 데이터베이스의 데이터 유형이나 테이블 구조에 의해 제한되지 않습니다. API 소비자에게 가장 적합한 방식으로 응답을 구성할 수 있습니다. JSON이 가장 일반적으로 사용되는 형식이지만 필요한 경우 XML 또는 CSV와 같은 다른 형식으로 데이터를 자유롭게 반환할 수 있습니다.

예: GET /reports/{reportId} 엔드포인트는 요청의 쿼리 매개변수 또는 헤더를 기반으로 다양한 형식(JSON, CSV, PDF)으로 보고서를 반환할 수 있습니다.
API 구조 예
이러한 모든 원칙을 하나로 묶기 위해 다음 모범 사례를 따르는 샘플 API 구조가 있습니다.

GET /products: 모든 제품을 검색합니다.
GET /products/{productId}: 특정 제품의 세부정보를 검색합니다.
POST /products: 새 제품을 생성합니다.
PUT /products/{productId}: 제품을 productId로 바꿉니다.
패치 /products/{productId}: 제품을 부분적으로 업데이트합니다.
DELETE /products/{productId}: 제품을 삭제합니다.
이 구조에서는 리소스가 명확하게 정의되고 HTTP 메서드가 수행할 작업을 지정하여 깔끔하고 직관적인 API를 보장합니다.

**결론
**RESTful API 설계에는 경로 생성 및 HTTP 메서드 처리 이상의 작업이 포함됩니다. 리소스에 집중하고, 작업에 HTTP 메서드를 활용하고, 상태 비저장을 준수함으로써 직관적이고 유지 관리 및 확장 가능한 API를 만들 수 있습니다. API는 유연하고 특정 데이터베이스 구조에 독립적이어야 하며 시스템이 성장함에 따라 더 많은 적응성을 허용해야 한다는 점을 기억하세요.

이러한 규칙을 따르면 API 디자인이 효율적이고 사용자 친화적이며 궁극적으로 API 개발자와 소비자 모두의 경험이 향상됩니다.