Designing a REST API for a Custom Business CRM: Best Practices

The REST API is the backbone of any custom-built CRM. It must be stable, scalable, and consistent — because changing an API contract once clients are consuming it is expensive. Here are the design decisions I make systematically on every project.

Versioning from Day One

Always prefix your endpoints with a version: /api/v1/contacts, /api/v1/opportunities. When you need to make breaking changes (renaming a field, restructuring a response), you can introduce /api/v2/ without breaking existing clients. This one detail prevents painful migrations 12 months down the road.

Strict Naming Conventions

• →Plural resource names: /contacts, /opportunities, /invoices (not /contact or /getContacts)
• →URL hierarchy for relationships: /contacts/{id}/activities, /opportunities/{id}/notes
• →HTTP verbs for actions: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
• →Avoid verbs in URLs: /contacts/{id}/activate rather than /activateContact/{id}

Pagination, Filtering, and Sorting

• →Cursor-based pagination rather than offset for large collections
• →Filters via query params: /contacts?status=active&owner_id=123
• →Sorting: /contacts?sort=created_at&order=desc
• →Always cap response size: define a max page_size based on actual usage

Consistent Error Handling

• →Standard HTTP codes: 200 (OK), 201 (created), 400 (bad request), 401 (unauthenticated), 403 (forbidden), 404 (not found), 422 (validation error), 500 (server error)
• →Standardized error body: { code, message, details } — always the same format
• →Detailed validation errors: { field, constraint, value } for each invalid field

Auto-Generated Swagger Documentation

With NestJS + @nestjs/swagger, OpenAPI documentation is automatically generated from TypeScript decorators. Every developer (frontend, integration partner, QA) gets up-to-date docs with zero manual effort. It's a significant time saver over the lifetime of the project.