REST API Documentation

⚠ Original Design Issues Fixed

GET /getUsers ✓ GET /users Verbs don't belong in URLs. The HTTP method IS the verb. Resources are nouns, pluralised.

POST /user/delete/5 ✓ DELETE /users/5 Use the DELETE method for deletion. Embedding actions in the path violates REST. Resource name should also be plural.

GET /createUser?name=Jo ✓ POST /users { "name": "Jo" } GET must be safe and idempotent — never use it to create resources. Creation data belongs in the request body, not the query string. Use POST.

PUT /updateAllUsers ✓ PATCH /users Again, no verbs in paths. PUT implies full replacement of a known resource. Bulk partial updates should use PATCH. The intent here is an update, not a wholesale replace.

Base URL https://api.example.com/v2

Collection — /users

GET /users List all users fixed ▼

Returns a paginated list of all users. Supports filtering by status and sorting.

Was: GET /getUsers — verb in URL, resource not pluralised.

Query Parameters

Name	Type	Description
pageoptional	integer	Page number, default 1
limitoptional	integer	Results per page, default 20, max 100
statusoptional	string	Filter by status: `active` \| `inactive`
sortoptional	string	Sort field, e.g. `name`, `-createdAt`

Responses

200 Paginated user list returned

400 Invalid query parameters

401 Unauthorised

Example Response — 200 OK

{
  "data": [
    {
      "id":        1,
      "name":      "Alice",
      "email":     "[email protected]",
      "status":    "active",
      "createdAt": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page":       1,
    "limit":      20,
    "total":      84,
    "totalPages": 5
  }
}

POST /users Create a user fixed ▼

Creates a new user. Returns the created resource with its assigned id.

Was: GET /createUser?name=Jo — GET must never mutate state. Verb in URL. Sensitive/structured data must not go in query strings; it belongs in the request body.

Request Body application/json

Field	Type	Description
namerequired	string	Full name, min 1 char
emailrequired	string	Valid unique email address
roleoptional	string	`user` \| `admin`, default `user`

Responses

201 User created, resource returned

400 Validation error

409 Email already exists

401 Unauthorised

Example Request

{
  "name":  "Jo",
  "email": "[email protected]",
  "role":  "user"
}

Example Response — 201 Created

{
  "id":        42,
  "name":      "Jo",
  "email":     "[email protected]",
  "role":      "user",
  "createdAt": "2024-06-01T12:00:00Z"
}

PATCH /users Bulk-update users fixed ▼

Partially updates multiple users in a single request.

Was: PUT /updateAllUsers — verb in URL. PUT semantics mean full replacement of a known single resource with a required ID; that's wrong for a bulk partial update. PATCH on the collection is the correct choice. A PUT here would require sending every field of every user or risk data loss.

Request Body application/json — array of partial user objects

Field	Type	Description
idrequired	integer	ID of user to update
nameoptional	string	New name
emailoptional	string	New email
statusoptional	string	`active` \| `inactive`

Example Request

[
  { "id": 1, "status": "inactive" },
  { "id": 2, "name":   "Bob"       }
]

Responses

200 All updates applied, results returned

207 Multi-status — partial success

400 Validation error

401 Unauthorised

Item — /users/{id}

GET /users/{id} Get a single user ▼

Returns a single user by their unique ID.

Path Parameters

Name	Type	Description
idrequired	integer	User's unique identifier

Responses

200 User object returned

404 User not found

401 Unauthorised

Example Response — 200 OK

{
  "id":        5,
  "name":      "Alice",
  "email":     "[email protected]",
  "role":      "admin",
  "status":    "active",
  "createdAt": "2024-01-15T09:00:00Z"
}

PUT /users/{id} Replace a user (full update) ▼

Fully replaces a user resource. All fields must be supplied. Missing fields will be set to their defaults or null — this is the correct semantic for PUT. Use PATCH /users/{id} if you only want to update specific fields.

Request Body

Field	Type	Description
namerequired	string	Full name
emailrequired	string	Email address
rolerequired	string	`user` \| `admin`
statusrequired	string	`active` \| `inactive`

Responses

200 User replaced, updated resource returned

400 Validation error

404 User not found

401 Unauthorised

PATCH /users/{id} Partially update a user ▼

Updates only the supplied fields of a user. Omitted fields are left unchanged.

Request Body all fields optional, at least one required

Field	Type	Description
nameoptional	string	New name
emailoptional	string	New email
roleoptional	string	`user` \| `admin`
statusoptional	string	`active` \| `inactive`

Responses

200 Updated resource returned

400 Validation error

404 User not found

401 Unauthorised

DELETE /users/{id} Delete a user fixed ▼

Permanently deletes a user by ID.

Was: POST /user/delete/5 — POST is for creation. Deletion semantics belong to the DELETE method. Embedding the action delete in the path is redundant once you use the right verb. Resource name must also be plural.

Path Parameters

Name	Type	Description
idrequired	integer	ID of user to delete

Responses

204 Deleted successfully, no content

404 User not found

401 Unauthorised

403 Forbidden — insufficient permissions