API Design That Developers Love

Good APIs Feel Obvious

When developers can guess how your API works, you've done it right.

Use Nouns, Not Verbs

# Good
GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123

# Bad
GET /getUsers
POST /createUser
POST /deleteUser/123

The HTTP method is the verb.

Consistent Naming

Pick a style and stick to it:

# Plural nouns
/users, /posts, /comments

# Nested resources
/users/123/posts
/posts/456/comments

# Snake_case or camelCase (pick one)
created_at or createdAt

Proper Status Codes

200 - Success
201 - Created
204 - No Content (successful delete)
400 - Bad Request (client error)
401 - Unauthorized (not logged in)
403 - Forbidden (logged in, no permission)
404 - Not Found
422 - Validation Error
500 - Server Error

Pagination

Always paginate lists:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 150
  },
  "links": {
    "next": "/users?page=2",
    "prev": null
  }
}

Error Responses

Be helpful:

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": {
      "email": ["The email field is required."],
      "password": ["Password must be at least 8 characters."]
    }
  }
}

Versioning

Include version in the URL or header:

/api/v1/users
# or
Accept: application/vnd.api+json; version=1

Start with v1 even if you don't plan to change it.