DEV Community

Dev Cookies
Dev Cookies

Posted on

📘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 <token>
Enter fullscreen mode Exit fullscreen mode
  • 🚫 401 Unauthorized: Missing/invalid token
  • 🚫 403 Forbidden: Insufficient permission for resource

🛠️ Common Request Headers

Header Required Value Description
Authorization ✅ Bearer <token> Auth header
Content-Type ✅ application/json Format of request body
Accept ✅ application/json Expected response format
X-Request-ID ❌ <uuid> Optional for tracing/debugging

📤 Common Response Headers

Header Description
Content-Type application/json
X-Request-ID Echoed back from request (for traceability)
X-Rate-Limit Requests allowed in a time window
Retry-After Returned on 429 Too Many Requests

📂 Resource: /users

1️⃣ GET /users — Get All Users

✅ Request 

GET /users HTTP/1.1
Authorization: Bearer eyJhbGci...
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

📥 Request Body:

None

📤 Response: 200 OK 

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-ID: 98219cda-21e8
Enter fullscreen mode Exit fullscreen mode 
[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "createdAt": "2023-01-01T10:00:00Z"
  }
]
Enter fullscreen mode Exit fullscreen mode

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

✅ Request 

GET /users/1 HTTP/1.1
Authorization: Bearer eyJhbGci...
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

📥 Path Parameter:

Param Type Description
id int User’s unique ID

📤 Response: 200 OK 

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

❌ Response: 404 Not Found 

{
  "error": "User with ID 99 not found"
}
Enter fullscreen mode Exit fullscreen mode

3️⃣ POST /users — Create a New User

✅ Request 

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

📥 Request Body 

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

🔐 Password must be encrypted at backend before storing in DB

📤 Response: 201 Created 

Location: /users/2
Enter fullscreen mode Exit fullscreen mode 
{
  "id": 2,
  "name": "Alice Smith",
  "email": "alice@example.com"
}
Enter fullscreen mode Exit fullscreen mode

❌ Response: 400 Bad Request 

{
  "error": "Email already in use"
}
Enter fullscreen mode Exit fullscreen mode

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

✅ Request 

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

📥 Request Body 

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

📤 Response: 200 OK 

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

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

✅ Request 

DELETE /users/1 HTTP/1.1
Authorization: Bearer eyJhbGci...
Enter fullscreen mode Exit fullscreen mode

📤 Response: 204 No Content

No response body.

❌ 404 Not Found 

{
  "error": "User not found"
}
Enter fullscreen mode Exit fullscreen mode

⚠️ Standard Error Format (used in all endpoints) 

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

📚 Versioning

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

🧪 Rate Limiting

Header Description
X-Rate-Limit Requests allowed per minute
Retry-After Seconds to wait before retrying

🛡️ 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

Area Sample Question
REST What are idempotent methods?
Auth How would you secure these APIs?
Headers What's the purpose of X-Request-ID or ETag?
Versioning How do you support multiple versions of an API?
Pagination How do you return paginated responses?
Error Handling How do you standardize error responses?
Rate Limiting How do you prevent abuse of APIs?

Top comments (0)