[Computer Science] 엔드포인트 규칙

백엔드 서버 엔드포인트를 설계할 때, 각 규칙에 따라 엔드포인트를 정리해 볼 수 있음.

주로 자원 중심 방식과 동작 중심 방식으로 나뉘며, HTTP 메소드와 자원의 관계에 따라 이름이 결정됨.

1. 자원 중심 방식 (Resource-Oriented)
   • RESTful한 구조를 따르는 엔드포인트 설계에 적합
   • 주로 명사를 사용하여 자원을 나타내며, CRUD 동작을 HTTP 메소드로 구분
   • 자원(collection)과 자원의 개별 요소(item)에 접근할 때 경로를 명확히 구분
   예시:
   • GET /users: 모든 사용자 목록 조회
   • GET /users/{userId}: 특정 사용자 상세 정보 조회
   • POST /users: 새로운 사용자 생성
   • PUT /users/{userId}: 특정 사용자 정보 전체 업데이트
   • DELETE /users/{userId}: 특정 사용자 삭제
2. 동작 중심 방식 (Action-Oriented)
   • 특정 작업을 명시적으로 나타낼 때 효과적
   • 리소스 대신 동작에 중점을 두고 동사를 사용해 엔드포인트를 구성
   • 특정한 비즈니스 로직이나 동작이 필요한 경우 사용
   예시:
   • POST /auth/login: 사용자 로그인
   • POST /auth/logout: 사용자 로그아웃
   • POST /users/{userId}/activate: 특정 사용자 활성화
   • POST /users/{userId}/deactivate: 특정 사용자 비활성화
   • POST /orders/{orderId}/cancel: 특정 주문 취소
3. 계층 구조 방식 (Hierarchical)
   • 자원 간의 계층 관계를 나타내며, 자원들이 부모-자식 관계로 연결됨
   • 특정 자원의 하위 자원에 접근할 때 적합
   예시:
   • GET /users/{userId}/posts: 특정 사용자가 작성한 모든 게시글 조회
   • POST /users/{userId}/posts: 특정 사용자가 작성한 게시글 생성
   • GET /users/{userId}/posts/{postId}: 특정 사용자가 작성한 특정 게시글 조회
   • PUT /users/{userId}/posts/{postId}: 특정 사용자가 작성한 특정 게시글 업데이트
   • DELETE /users/{userId}/posts/{postId}: 특정 사용자가 작성한 특정 게시글 삭제
4. 필터 및 정렬 방식 (Filter and Sort)
   • 자원을 필터링하거나 정렬하는 기능을 쿼리 파라미터에 포함하여 설계
   • 검색 및 조건부 조회에 유용
   예시:
   • GET /products?category=electronics: 특정 카테고리의 제품 목록 조회
   • GET /products?sort=price&order=desc: 가격 기준 내림차순 정렬 제품 조회
   • GET /orders?status=pending: 대기 중인 주문 조회
   • GET /users?role=admin: 관리자인 사용자 조회
   • GET /posts?authorId=123&tag=tech: 특정 작성자와 태그가 포함된 게시글 조회
5. 상태 관리 방식 (State Management)
   • 특정 상태에 따라 자원이나 요청을 다루는 경우 사용
   • 자원의 상태를 명시적으로 나타냄
   예시:
   • PATCH /orders/{orderId}/status: 특정 주문 상태 업데이트
   • GET /orders?status=completed: 완료된 주문 조회
   • POST /projects/{projectId}/archive: 프로젝트 아카이브 처리
   • POST /projects/{projectId}/restore: 아카이브된 프로젝트 복구
   • GET /tasks?status=pending: 대기 중인 작업 조회
6. 배치 처리 방식 (Batch Operations)
   • 여러 자원에 대해 동시에 작업을 수행
   • JSON 배열이나 특정 포맷으로 여러 요청을 한 번에 처리 가능
   예시:
   • POST /users/batch: 여러 사용자 동시에 생성
   • DELETE /posts/batch: 여러 게시글 동시에 삭제
   • PATCH /products/batch-update: 여러 제품 일괄 업데이트
   • POST /orders/batch-cancel: 여러 주문 동시에 취소
   • PUT /tasks/batch-complete: 여러 작업 동시에 완료 처리
7. 관계 표현 방식 (Relationship Representation)
   • 두 자원의 관계를 명시적으로 표현
   • 자원 간 관계를 명확히 함
   예시:
   • POST /users/{userId}/friends/{friendId}: 사용자와 친구 관계 생성
   • DELETE /users/{userId}/friends/{friendId}: 사용자와 친구 관계 해제
   • GET /products/{productId}/reviews: 특정 제품의 리뷰 목록 조회
   • POST /posts/{postId}/like: 특정 게시글에 좋아요 추가
   • DELETE /posts/{postId}/like: 특정 게시글에서 좋아요 제거
8. 버전 관리 방식 (Versioning)
   • API의 버전을 명시해, 변경 사항을 적용할 때 과거 버전과 호환성 유지
   • URL 또는 헤더에 버전을 명시
   예시:
   • GET /v1/users: 사용자 목록 조회 (버전 1)
   • GET /v2/users: 사용자 목록 조회 (버전 2, 새로운 필드 포함)
   • POST /v1/auth/login: 로그인 기능 (버전 1)
   • POST /v2/auth/login: 로그인 기능 (버전 2, 추가 인증 방식 포함)
   • GET /v1/products/{productId}: 제품 정보 조회 (버전 1)
9. 이벤트 트리거 방식 (Event Trigger)
   • 자원에 대한 특정 이벤트나 트리거를 기반으로 동작 수행
   • 비동기 작업이나 알림, 예약 작업에 사용
   예시:
   • POST /users/{userId}/notify: 특정 사용자에게 알림 전송
   • POST /reports/generate: 보고서 생성 작업 트리거
   • POST /emails/send/{templateId}: 특정 이메일 템플릿 사용해 발송
   • POST /tasks/{taskId}/remind: 특정 작업에 대해 알림 전송
   • POST /subscriptions/{subscriptionId}/renew: 구독 갱신 작업 트리거
10. 복합 작업 방식 (Composite Operations)

• 여러 작업을 하나의 엔드포인트에서 수행해 복합 작업 처리
• 하나의 요청으로 여러 자원을 생성하거나 업데이트 가능

예시:

• POST /orders/complete-and-send-invoice: 주문 완료 후 송장 발송
• POST /users/register-and-subscribe: 사용자 등록 후 구독 신청
• POST /posts/publish-and-notify: 게시글 게시 후 알림 전송
• POST /projects/initiate-and-assign: 프로젝트 시작 후 담당자 할당
• POST /carts/{cartId}/checkout-and-pay: 장바구니 결제 후 주문 완료