Good API = Predictable, Stable, and Boring
Here’s the checklist:
1. Clear Purpose
Every endpoint should have one job.
/users gets users.
/users/{id} gets a specific user.
NOT /getEverythingAndAlsoMaybeDelete.
2. Consistent Naming
If you use /users for list, don’t suddenly use /getAllAccounts.
Consistency means devs don’t have to re-learn the rules for every endpoint.
GET /users
GET /users/{id}
POST /users
NOT GET /find-user-by-id
3. HTTP Methods Done Right
- GET = Fetch data
- POST = Create
- PUT/PATCH = Update
- DELETE = Remove
Don’t be that API that deletes data with a GET request.
4. Good Responses
Return the right HTTP status codes:
- 200 OK = Success
- 201 Created = New resource made
- 400 Bad Request = Client messed up
- 404 Not Found = Resource doesn’t exist
- 500 Internal Server Error = You messed up
And always return JSON with a predictable shape.
5. Versioning
Breaking changes happen. Be honest about it.
/api/v1/users → /api/v2/users
Don’t quietly change behavior and hope nobody notices.
6. Validation
Don’t trust the client. Validate everything.
Bad data should die at the door, not sneak into your DB.
7. Documentation
If someone needs to email you to understand your API, you failed.
Use OpenAPI/Swagger. Keep it updated.
Golden Rule:
A good API feels like muscle memory.
You shouldn’t need to keep the docs open once you’ve used it a few times.
Boring APIs are the best APIs. They last. They scale. They don’t surprise you.
📌 Follow along weekly right here or catch me on LinkedIn - building APIs that don’t make you cry.