APIs are contracts. Unlike UI code that can be iterated freely, a published API endpoint creates a commitment to every consumer that depends on it. Getting API design right the first time saves enormous pain down the road.
After building APIs for over 50 production projects, here are the principles we follow at KodexApps.
Naming Conventions That Scale
Use nouns, not verbs. /users, /orders, /invoices — not /getUsers, /createOrder
Plural for collections. GET /users returns a list, GET /users/123 returns one
Nest for relationships. GET /users/123/orders — but limit nesting to two levels
Kebab-case for multi-word. /order-items, not /orderItems or /order_items
Pagination Done Right
Every list endpoint needs pagination from day one, even if you only have 10 records. Cursor-based pagination is superior to offset-based for most use cases:
No skipped or duplicated items when data changes between pages
Consistent performance regardless of how deep you paginate
Works naturally with real-time data streams
Error Handling as a Feature
Good error responses are the difference between an API that developers love and one they dread. Every error response should include:
A machine-readable error code (not just the HTTP status)
A human-readable message that explains what went wrong
A pointer to the field that caused the error (for validation errors)
A documentation link for complex error scenarios
Versioning Strategy
URL-based versioning (/v1/users, /v2/users) is simple and explicit. Header-based versioning is cleaner but harder to test. We recommend URL-based for external APIs and header-based for internal microservice communication.
The most important rule: never break an existing version. Add fields, never remove them. Deprecate gradually with clear timelines.
Good API design is where we Dream. Develop. Innovate. — we dream about the ideal developer experience, develop clean contracts, and innovate on patterns as the API ecosystem evolves.