📘User Management REST API Documentation

📍 Base URL: https://api.example.com/v1

🔒 Authentication & Authorization

• 🔑 Auth Type: Bearer Token (JWT or OAuth 2.0)
• 📥 Header Required:

Authorization: Bearer

• 🚫 401 Unauthorized: Missing/invalid token
• 🚫 403 Forbidden: Insufficient permission for resource

🛠️ Common Request Headers

📤 Common Response Headers

📂 Resource: /users

1️⃣ GET /users — Get All Users

✅ Request

GET /users HTTP/1.1
Authorization: Bearer eyJhbGci...
Accept: application/json

📥 Request Body:

None

📤 Response: 200 OK

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: 98219cda-21e8

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2023-01-01T10:00:00Z"
  }
]

2️⃣ GET /users/{id} — Get User by ID

✅ Request

GET /users/1 HTTP/1.1
Authorization: Bearer eyJhbGci...
Accept: application/json

📥 Path Parameter:

📤 Response: 200 OK

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "createdAt": "2023-01-01T10:00:00Z"
}

❌ Response: 404 Not Found

{
  "error": "User with ID 99 not found"
}

3️⃣ POST /users — Create a New User

✅ Request

POST /users HTTP/1.1
Authorization: Bearer eyJhbGci...
Content-Type: application/json
Accept: application/json

📥 Request Body

{
  "name": "Alice Smith",
  "email": "alice@example.com",
  "password": "SecureP@ss123"
}

🔐 Password must be encrypted at backend before storing in DB

📤 Response: 201 Created

Location: /users/2

{
  "id": 2,
  "name": "Alice Smith",
  "email": "alice@example.com"
}

❌ Response: 400 Bad Request

{
  "error": "Email already in use"
}

4️⃣ PUT /users/{id} — Update a User

✅ Request

PUT /users/1 HTTP/1.1
Authorization: Bearer eyJhbGci...
Content-Type: application/json

📥 Request Body

{
  "name": "Alice M. Smith",
  "email": "alice.m@example.com"
}

📤 Response: 200 OK

{
  "id": 1,
  "name": "Alice M. Smith",
  "email": "alice.m@example.com"
}

5️⃣ DELETE /users/{id} — Delete a User

✅ Request

DELETE /users/1 HTTP/1.1
Authorization: Bearer eyJhbGci...

📤 Response: 204 No Content

No response body.

❌ 404 Not Found

{
  "error": "User not found"
}

⚠️ Standard Error Format (used in all endpoints)

{
  "timestamp": "2024-04-05T12:34:56Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Email already exists",
  "path": "/users"
}

📚 Versioning

• Best practice is to version via URI: /v1/users
• Alternatively, use headers: Accept: application/vnd.api+json;version=1.0

🧪 Rate Limiting

🛡️ Security Best Practices

• Use HTTPS for all requests
• Validate and sanitize all inputs
• Do not expose internal IDs directly (consider UUIDs)
• Hash passwords using bcrypt or similar
• Use CSRF protection if needed for browser-based clients

💬 Common Interview Questions to Prepare