드디어 시작 된 팀 프로젝트...
갈길이 멀고 이걸 과연 10일정도밖에 안되는 시간에 적절히 구현할 수 있을 지 의문이 들긴하지만 일단 시작을 하면 팀원들끼리 뭉쳐 어떻게든 되지 않을까 기도해본다.
본격적인 프로젝트 시작 전에 API 명세서를 직접 작성하면서 실제 엔드포인트 설계가 어떻게 이루어지는지 이해하고,
사용자 관리라는 도메인에서 CRUD 작업과 상태 관리를 어떻게 API로 표현하는지부터 시작했다.
REST API는 자원(resource)을 URL로 표현하고, HTTP 메서드(GET, POST, PATCH, DELETE)로 행동을 정의한다.
사용자 관리 API를 설계할 때는 사용자라는 자원을 중심으로 여러 엔드포인트가 생기는데,
단순한 CRUD만 아니라 역할 변경, 상태 변경처럼 부분적 업데이트가 필요한 경우를 어떻게 처리할지가 설계의 핵심이다.
응답 구조는 성공/실패를 일관되게 표현하기 위해 success, code, data 같은 필드를 정의하고,
클라이언트가 예측 가능한 형태로 데이터를 받을 수 있도록 한다.
내가 구현을 맡게된 파트는 "관리자 정보 관리"
분량이 꽤나 많아보이지만 비슷한 구조속에서 내용만 조금조금씩 변경되는 형태여서 작성하다보니 그리 복잡하진 않았다.
작성한 사용자 관리 API는 다음과 같이 구성된다.
사용자 목록 조회는 GET /api/users에서
page=1&limit=10&sortBy=createdAt&sortOrder=desc
같은 쿼리 파라미터로 클라이언트가 원하는 데이터 범위를 지정할 수 있다. 응답은 배열 형태로 여러 사용자 객체를 반환하며, 각 객체는 id, name, email, phone, role, status, createdAt, approvedAt, rejectedAt을 포함한다. status 값이 PENDING, ACTIVE, INACTIVE, SUSPENDED, REJECTED 같이 여러 상태를 가질 수 있다는 점이 중요한데, 이는 사용자가 단순히 있거나 없는 것이 아니라 승인 대기 중이거나 정지 상태일 수 있음을 의미한다.
사용자 상세 조회는 GET /api/users/{id}로 특정 사용자의 전체 정보를 조회한다.
응답 구조는 목록과 동일하지만 단일 객체를 반환한다.
사용자 정보 수정은 PATCH /api/users/{id}로 진행하며,
이 엔드포인트는 기본 정보(이름, 이메일, 전화번호)를 업데이트한다.
PATCH를 사용한 것은 부분 업데이트를 표현하기 위함이고, PUT을 쓰면 전체 객체를 교체한다는 의미가 된다.
사용자 역할 변경은 PATCH /api/users/{id}/role에서 처리한다.
단순히 PATCH /api/users/{id}로 role 필드만 보낼 수도 있지만,
역할 변경이 일반 정보 수정과 다른 비즈니스 로직을 가질 때(예: 권한 확인이나 로그 기록) 이렇게 분리하는 것이 명확하고 유지보수하기 쉽다고 한다.
사용자 상태 변경은 PATCH /api/users/{id}/status로 PENDING을 ACTIVE로, ACTIVE를 SUSPENDED로 바꾸는 같은 상태 전환을 처리한다.
status 값이 APPROVED, REJECTED 같은 승인/거절 결과와 관련되어 있다.
사용자 삭제는 DELETE /api/users/{id}로 진행하며, 응답은 success: true와 message로 간단히 처리한다.
현재 사용자 정보는 GET /api/users/me로 조회하는데, 이는 인증된 사용자가 자신의 정보를 받기 위한 엔드포인트이다.
현재 사용자 정보 수정은 PUT /api/users/me로 진행한다. 여기서 PUT을 사용한 이유는 자신의 정보 전체를 업데이트하기 때문.
비밀번호 변경은 POST /api/auth/password에서 처리하는데, auth 엔드포인트에 속한다.
비밀번호 변경은 사용자 자신의 보안 정보를 다루기 때문에 인증 영역의 작업이고,
다른 관리자가 사용자의 비밀번호를 초기화하는 경우 등 별도의 비즈니스 로직이 복잡할 수 있기 때문이다.
응답 구조는 모든 엔드포인트에서 일관된 형태를 유지한다. 목록 조회 같은 경우 배열을 직접 반환하기도 하고, 상세 조회나 생성/수정/삭제는 "success": true, "code": "OK", "data": {...} 형태로 응답한다. 이렇게 일관되게 유지하면 클라이언트에서 응답을 처리하기 쉬워진다.
API 명세서를 직접 작성하면서 느낀 점은, 엔드포인트를 만들 때 단순히 기능만 생각하면 안 되고 비즈니스 로직과 사용 시나리오등 제작 의도를 함께 생각해야 한다는 것이다.
역할 변경과 상태 변경을 왜 별도 엔드포인트로 분리했는지, 비밀번호 변경을 왜 /users가 아니라 /auth에 두었는지 같은 결정들이 모두 실제 시스템에서 필요한 선택이라는 걸 알게 됐다.
응답 구조를 일관되게 유지하는 것도 중요했다.
각각 다른 형태로 응답하면 클라이언트 코드에서 매번 다르게 처리해야 하는데,
통일된 구조를 정하면 처리 로직을 재사용할 수 있어서 편리하다고 한다.
REST API 설계의 기본은 자원을 URL로 표현하고 HTTP 메서드로 행동을 정의하는 것이다.
사용자 관리 API는 목록 조회, 상세 조회, 정보 수정, 역할 변경, 상태 변경, 삭제, 현재 사용자 조회, 비밀번호 변경 같은 엔드포인트로 구성된다.
비즈니스 로직이 복잡한 작업(역할 변경, 상태 변경)은 별도 엔드포인트로 분리하고, 응답 구조는 모든 엔드포인트에서 일관되게 유지하는 것이 설계의 핵심이다. 이렇게 설계된 API는 백엔드에서 구현할 때 각 엔드포인트마다 필요한 권한 확인과 비즈니스 로직을 명확하게 적용할 수 있다.