JSON API Design Best Practices

1. Use Consistent Naming Conventions

✅ Use camelCase for JSON keys:

{
  "userId": 123,
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john@example.com"
}

❌ Avoid inconsistent naming:

{
  "user_id": 123,           // snake_case
  "FirstName": "John",      // PascalCase
  "last-name": "Doe",       // kebab-case
  "email": "john@example.com"
}

2. Use HTTP Status Codes Correctly

• 200 OK: Successful GET, PUT, PATCH
• 201 Created: Successful POST creating resource
• 204 No Content: Successful DELETE
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 500 Internal Server Error: Server-side error

3. Consistent Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid user data",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      },
      {
        "field": "age",
        "message": "Age must be greater than 0"
      }
    ]
  }
}

4. Use Plural Nouns for Collections

✅ Good:

GET /api/users
GET /api/users/123
POST /api/users
PUT /api/users/123
DELETE /api/users/123

❌ Bad:

GET /api/getUsers
GET /api/user/123
POST /api/createUser
DELETE /api/deleteUser/123

5. Include Metadata in Responses

{
  "data": [
    {
      "id": 1,
      "name": "John"
    },
    {
      "id": 2,
      "name": "Jane"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 10,
    "total": 100,
    "totalPages": 10
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2",
    "prev": null,
    "first": "/api/users?page=1",
    "last": "/api/users?page=10"
  }
}

6. Support Filtering, Sorting, and Pagination

# Filtering
GET /api/users?role=admin&status=active

# Sorting
GET /api/users?sort=createdAt&order=desc

# Pagination
GET /api/users?page=2&perPage=20

# Combined
GET /api/users?role=admin&sort=name&order=asc&page=1&perPage=10

7. Version Your API

Option 1: URL Versioning (Recommended)

GET /api/v1/users
GET /api/v2/users

Option 2: Header Versioning

GET /api/users
Headers: Accept: application/vnd.myapi.v2+json

8. Use ISO 8601 for Dates

{
  "createdAt": "2026-01-21T10:30:00Z",
  "updatedAt": "2026-01-21T15:45:30.500Z",
  "birthDate": "1990-05-15"
}

9. Implement HATEOAS (Hypermedia Links)

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": {
      "href": "/api/users/123"
    },
    "posts": {
      "href": "/api/users/123/posts"
    },
    "followers": {
      "href": "/api/users/123/followers"
    }
  }
}

10. Rate Limiting Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642771200

When limit exceeded, return 429:

HTTP/1.1 429 Too Many Requests
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retryAfter": 60
  }
}

11. Security Best Practices

• Always use HTTPS in production
• Validate all inputs server-side
• Use authentication (JWT, OAuth2)
• Implement authorization checks
• Sanitize output to prevent XSS
• Rate limit to prevent abuse
• Log security events

12. Documentation is Essential

Use tools like:

• OpenAPI/Swagger: Industry standard
• Postman: API testing and documentation
• API Blueprint: Markdown-based documentation

Complete Example: Well-Designed API Response

{
  "status": "success",
  "data": {
    "id": 123,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "role": "admin",
    "isActive": true,
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-21T14:20:00Z"
  },
  "meta": {
    "timestamp": "2026-01-21T15:30:00Z",
    "apiVersion": "v1"
  },
  "_links": {
    "self": {
      "href": "/api/v1/users/123",
      "method": "GET"
    },
    "update": {
      "href": "/api/v1/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "/api/v1/users/123",
      "method": "DELETE"
    },
    "posts": {
      "href": "/api/v1/users/123/posts",
      "method": "GET"
    }
  }
}

Tools for Testing Your API

Conclusion

Following these JSON API best practices will make your APIs more consistent, easier to use, and more maintainable. Remember: good API design is about making life easier for your users (developers).