Users API

User management endpoints for creating, reading, updating, and deleting users.

Status

These endpoints are planned and not yet implemented.

Endpoints

List Users

Returns a paginated list of users. Requires authentication.

GET /api/users

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number
pageSize	integer	10	Items per page (max 100)
search	string	-	Search by name or email

Success Response 200 OK

{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "pageSize": 10
  }
}

Error Response 401 Unauthorized

User is not authenticated.

---

Get User

Returns a single user by their ID.

GET /api/users/{id}

Path Parameters

Parameter	Type	Description
id	guid	User ID

Success Response 200 OK

{
  "data": {
    "id": 1,
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "createdAt": "2026-01-01T00:00:00Z"
  },
  "error": null,
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "abc-123"
  }
}

Error Response 404 Not Found

User does not exist.

---

Create User

Creates a new user account.

POST /api/users

Request Body

{
  "email": "newuser@example.com",
  "password": "securePassword123",
  "firstName": "John",
  "lastName": "Doe"
}

Validation Rules

Field	Rules
email	Required, valid email format, unique
password	Required, min 8 characters
firstName	Required, max 50 characters
lastName	Required, max 50 characters

Success Response 201 Created

{
  "data": {
    "id": 2,
    "email": "newuser@example.com"
  },
  "error": null,
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "def-456"
  }
}

Error Response 400 Bad Request

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      { "field": "email", "message": "Email already exists" }
    ]
  },
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "ghi-789"
  }
}

---

Update User

Updates an existing user.

PUT /api/users/{id}

Path Parameters

Parameter	Type	Description
id	guid	User ID

Request Body

{
  "firstName": "Jane",
  "lastName": "Smith"
}

Success Response 200 OK

{
  "data": {
    "id": 1,
    "email": "user@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "error": null,
  "meta": {
    "timestamp": "2026-01-12T10:00:00Z",
    "requestId": "jkl-012"
  }
}

Error Response 404 Not Found

User does not exist.

---

Delete User

Deletes a user account. Requires admin privileges.

DELETE /api/users/{id}

Path Parameters

Parameter	Type	Description
id	guid	User ID

Success Response 204 No Content

No response body.

Error Responses

Status	Description
403 Forbidden	Admin access required
404 Not Found	User does not exist

---

Frontend Integration

// features/users/hooks/useUsers.ts
export function useUsers(params?: { page?: number; search?: string }) {
  return useQuery({
    queryKey: ['users', params],
    queryFn: () => usersApi.getAll(params),
  });
}

export function useCreateUser() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateUserRequest) => usersApi.create(data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] });
    },
  });
}