API Guide
API Design Best Practices for Business Applications
Well-designed APIs are consistent, versioned, and documented. They scale with your business. Here are the practices we follow for business applications.
Table of Contents
REST Conventions
- Resources as nouns: /users not /getUsers
- HTTP methods: GET, POST, PUT, PATCH, DELETE
- Plural: /users not /user
- Nested for relations: /users/123/orders
Versioning
Version in path: /v1/users. Or header. Deprecate old versions with notice. See our Enterprise API Strategy.
Error Handling
Consistent format: code, message, details. HTTP status codes. 4xx client, 5xx server. Don't leak internals.
Documentation
OpenAPI/Swagger. Examples, error codes. Keep in sync with code. API portal for discoverability.
Frequently Asked Questions
REST vs GraphQL for new APIs?
REST for simple, standard. GraphQL when clients need flexible queries. See our REST vs GraphQL guide.