RESTful API 설계 규칙

REST(Representational State Transfer) 기반이란, 웹 서비스와 API(Application Programming Interface)를 설계하는 아키텍처 스타일로, REST의 주요 원칙은 다음과 같다.

• 클라이언트-서버 구조: 클라이언트와 서버는 서로 독립적이며, 클라이언트는 서버로부터 데이터를 요청하고 서버는 해당 요청에 응답하는 역할을 한다.
• 무상태성(Stateless): 서버는 각 요청을 독립적으로 처리하며, 이전 요청의 상태를 저장하지 않는다. 모든 요청은 필요한 모든 정보를 포함해야 한다.
• 캐시 처리 가능(Cachability): 클라이언트는 서버 응답을 캐시할 수 있으며, 이를 통해 성능을 최적화하고 서버에 대한 부하를 줄일 수 있다.
• 계층화 시스템(Layered System): 클라이언트는 중간 서버(게이트웨이, 프록시 등)를 통해 서버와 상호 작용할 수 있으며, 각 계층은 독립적으로 설계된다.
• 인터페이스 일관성(Uniform Interface): 리소스는 통일된 방식으로 접근되며, 특정 URL이 해당 리소스를 나타낸다.
• 리소스 기반 아키텍처: URL은 리소스를 나타내며, 리소스는 HTTP 메서드(주로 GET, POST, PUT, DELETE 등)에 따라 CRUD 작업을 수행한다.

REST API: 이는 REST(Representational State Transfer) 원칙을 따르는 API를 가리킨다. API가 완전히 REST 원칙을 준수하지 않아도 이 용어를 사용할 수 있다.

RESTful API: 이 용어는 REST 원칙을 더 충실하게 따르는 API를 의미한다. 즉, API가 엔드포인트와 자원을 의도된 데이터와 작업에 맞게 설계하고, HTTP 메소드(GET, POST, PUT, DELETE)를 적절히 활용하여 표준적인 방식으로 자원을 표현하는 API를 가리킨다.

API 엔드포인트 설계

이미지 출처

API 엔드포인트는 직관적이고 RESTful한 방식으로 구성하는 게 중요하다. RESTful API는 자원(Resource)을 중심으로 설계된다. 자원은 URL로 표현되며, 각 자원에 대해 HTTP 메서드를 사용해 CRUD(Create, Read, Update, Delete) 작업을 수행한다.

엔드포인트 설계 시 고려해야 할 요소

엔드포인트를 설계할 때는 다음과 같은 요소를 고려해야 한다.

• 명확한 URL 구조 : URL은 간결하고 직관적이어야 한다. 어떤 자원과 관계된 것인지 URL만으로 유추할 수 있으면 좋다. 직관적인가 의심이 들 경우 AI의 의견을 참고해보는 것도 도움이 될 것이다.
• HTTP 메서드의 적절한 사용 : 각 메서드는 특정 작업을 수행하기 위해 설계되었다. GET은 데이터를 가져오고, POST는 데이터를 생성하며, PUT은 데이터를 업데이트하고, DELETE는 데이터를 삭제한다.
• 상태 코드의 활용 : 클라이언트에게 요청의 결과를 알려주기 위해 적절한 HTTP 상태 코드를 반환해야 한다. 예를 들어, 요청이 성공하면 200 OK, 자원이 생성되면 201 Created, 요청이 잘못되면 400 Bad Request를 반환할 수 있다.

RESTful API 설계 규칙

1. 리소스는 복수형 명사
   리소스는 복수형 명사로 작성한다. 예를 들어, users, orders, products 등과 같이 작성한다.
   예시:
   GET /users → 모든 사용자 조회
   POST /orders → 주문 생성

2. 자원의 고유 ID는 URL에 포함
   특정 자원에 접근할 때는 해당 자원의 고유 ID를 URL에 포함한다.
   예시:
   GET /users/123 → ID가 123인 사용자 조회
   PUT /products/45 → ID가 45인 상품 수정

3. 계층적 관계 표현
   자원 간의 계층적 관계가 있을 경우 URL에 중첩해 표현한다. 자원 내의 하위 자원을 나타낼 때 유용하다.
   예시:
   GET /users/123/orders → ID가 123인 사용자의 주문 목록 조회
   POST /users/123/orders → ID가 123인 사용자에게 주문 생성

4. HTTP 메서드를 활용한 동작 정의
   HTTP 메서드(GET, POST, PUT, DELETE)를 통해 동작을 정의하므로, URL에는 동작을 나타내는 동사를 포함하지 않는다.
   GET → 조회 (Read)
   POST → 생성 (Create)
   PUT 또는 PATCH → 수정 (Update)
   DELETE → 삭제 (Delete)
   예시:
   DELETE /users/123 → ID가 123인 사용자 삭제
   PUT /products/45 → ID가 45인 상품 정보 수정

5. URL에는 소문자만 사용
   URL은 소문자만 사용하고, 단어는 하이픈(-)으로 구분한다. 대소문자 혼합은 일관성을 해칠 수 있다.
   예시:
   /user-profiles/123 (O)
   /UserProfiles/123 (X)

6. 필터링, 정렬, 페이징은 쿼리 파라미터로
   필터링, 정렬, 페이징과 같은 추가 조건은 URL 경로 대신 쿼리 파라미터를 사용하여 표현한다.
   예시:
   GET /products?category=books&sort=price_asc&page=2 → 책 카테고리의 제품을 가격 오름차순으로 정렬하고, 2페이지 결과 조회

7. 액션은 경로가 아닌 쿼리 파라미터로 표현
   일반적인 CRUD 작업이 아닌 특별한 동작이 필요한 경우, URL 경로 대신 쿼리 파라미터나 추가 경로로 표시한다.
   예시:
   POST /users/123/activate → ID가 123인 사용자를 활성화
   POST /orders/45/cancel → 주문을 취소

8. 경로 마지막에 '/'를 넣지 않는다.

자동화 툴

향후에는 API문서화와 테스트를 자동화하여 관리하고 싶어서 Apidog와 같은 툴을 이용해볼까 한다.
Apidog의 REST API URL 모범 사례