CRUD API Implementation Best Practices
This guide covers the standard conventions for implementing RESTful CRUD APIs in uc-enterprise-core, including request formats, response structures, pagination, filtering, and error handling.
Table of Contents
- Routing Conventions
- Request Format
- Response Format
- Pagination
- Filtering & Sorting
- Filter Operators Reference
- Error Handling
- Complete Examples
Routing Conventions
Follow RESTful resource naming with consistent HTTP method semantics:
| Method | Path | Action |
|---|---|---|
GET | /resource | List all (paginated) |
GET | /resource/:id | Get single record |
POST | /resource | Create new record |
PUT | /resource/:id | Full update |
PATCH | /resource/:id | Partial update |
DELETE | /resource/:id | Delete record |
Rules:
- Use plural nouns for resource names (
/users,/organizations,/calls) - Use kebab-case for multi-word resources (
/call-segments,/active-calls) - Never use verbs in the path — the HTTP method is the verb
- Nest resources when there is a clear parent–child relationship (
/organizations/:orgId/users)
Request Format
Headers
All API requests must include:
Content-Type: application/json
Authorization: Bearer <token>
Create (POST)
POST /api/v1/organizations
Content-Type: application/json
{
"organizationName": "Acme Corp",
"email": "admin@acme.com",
"phone": "+94771234567",
"countryId": 1,
"isActive": true
}
Update (PUT / PATCH)
PUT /api/v1/organizations/42
Content-Type: application/json
{
"organizationName": "Acme Corporation",
"email": "info@acme.com"
}
Delete (DELETE)
DELETE /api/v1/organizations/42
Response Format
All API responses follow a consistent envelope structure.
Single Record Response
{
"success": true,
"data": {
"id": 42,
"organizationName": "Acme Corp",
"email": "admin@acme.com",
"isActive": true,
"createdAt": "2026-09-01T08:00:00.000Z",
"updatedAt": "2026-09-18T10:30:00.000Z"
},
"message": "Record retrieved successfully"
}
List Response (with Pagination)
{
"data": [
{
"id": 1,
"organizationName": "Acme Corp",
"email": "admin@acme.com",
"isActive": true,
"createdAt": "2026-09-01T08:00:00.000Z"
},
{
"id": 2,
"organizationName": "Globex Inc",
"email": "info@globex.com",
"isActive": false,
"createdAt": "2026-09-05T09:15:00.000Z"
}
],
"pagination": {
"currentPage": 1,
"pageSize": 10,
"totalRecords": 45,
"totalPages": 5
}
}
Create / Update Success Response
{
"success": true,
"data": {
"id": 43,
"organizationName": "New Org",
"createdAt": "2026-09-18T12:00:00.000Z"
},
"message": "Organization created successfully"
}
Delete Success Response
{
"success": true,
"message": "Organization deleted successfully"
}
Pagination
Pagination is controlled via query parameters on list endpoints.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 10 | Number of records per page (max 100) |
offset | integer | 0 | Number of records to skip |
sortBy | string | id | Field name to sort by |
sortOrder | string | DESC | Sort direction: ASC or DESC |
Example Request
GET /api/v1/organizations?limit=10&offset=0&sortBy=id&sortOrder=DESC
Pagination Response Object
{
"data": [],
"pagination": {
"currentPage": 1,
"pageSize": 10,
"totalRecords": 0,
"totalPages": 0
}
}
| Field | Description |
|---|---|
currentPage | Current page number (1-based, derived from offset) |
pageSize | Number of items returned in this response |
totalRecords | Total number of matching records in the database |
totalPages | Total pages (Math.ceil(totalRecords / limit)) |
Computing currentPage
const currentPage = Math.floor(offset / limit) + 1;
const totalPages = Math.ceil(totalRecords / limit);
Filtering & Sorting
Filtering uses a rules-based query structure passed as URL-encoded query parameters.
Filter Structure
filterQuery[rules][{index}][field] = <fieldName>
filterQuery[rules][{index}][operator] = <operator>
filterQuery[rules][{index}][value] = <value>
Multiple rules are combined with AND logic by default.
Full Example (Decoded)
GET /api/v1/organizations
?limit=10
&offset=0
&sortBy=id
&sortOrder=DESC
&filterQuery[rules][0][field]=id
&filterQuery[rules][0][operator]=eq
&filterQuery[rules][0][value]=33
&filterQuery[rules][1][field]=organizationName
&filterQuery[rules][1][operator]=contains
&filterQuery[rules][1][value]=we
URL-Encoded Version
limit=10&offset=0&sortBy=id&sortOrder=DESC&filterQuery%5Brules%5D%5B0%5D%5Bfield%5D=id&filterQuery%5Brules%5D%5B0%5D%5Boperator%5D=eq&filterQuery%5Brules%5D%5B0%5D%5Bvalue%5D=33&filterQuery%5Brules%5D%5B1%5D%5Bfield%5D=organizationName&filterQuery%5Brules%5D%5B1%5D%5Boperator%5D=contains&filterQuery%5Brules%5D%5B1%5D%5Bvalue%5D=we
Parsed Filter Object (Server-side)
{
"rules": [
{ "field": "id", "operator": "eq", "value": "33" },
{ "field": "organizationName", "operator": "contains", "value": "we" }
]
}
Filter Operators Reference
| Operator | SQL Equivalent | Description |
|---|---|---|
eq | = value | Exact match |
neq | != value | Not equal |
contains | ILIKE '%value%' | Case-insensitive substring match |
notContains | NOT ILIKE '%value%' | Does not contain substring |
startsWith | ILIKE 'value%' | Starts with value |
endsWith | ILIKE '%value' | Ends with value |
gt | > value | Greater than |
gte | >= value | Greater than or equal |
lt | < value | Less than |
lte | <= value | Less than or equal |
in | IN (v1, v2, ...) | Value is in a list |
notIn | NOT IN (v1, v2, ...) | Value is not in a list |
isNull | IS NULL | Field is null |
isNotNull | IS NOT NULL | Field is not null |
between | BETWEEN v1 AND v2 | Value is within a range |
Using in Operator
Pass multiple values as a comma-separated string:
filterQuery[rules][0][field]=status
filterQuery[rules][0][operator]=in
filterQuery[rules][0][value]=active,pending,review
Using between Operator
Pass two values separated by a comma:
filterQuery[rules][0][field]=createdAt
filterQuery[rules][0][operator]=between
filterQuery[rules][0][value]=2026-01-01,2026-09-18
Error Handling
Error Response Format
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "organizationName is required",
"details": [
{
"field": "organizationName",
"message": "This field is required"
}
]
}
}
Standard HTTP Status Codes
| Status | Code | Usage |
|---|---|---|
200 | OK | Successful GET, PUT, PATCH |
201 | Created | Successful POST (record created) |
204 | No Content | Successful DELETE |
400 | Bad Request | Validation errors, malformed request body |
401 | Unauthorized | Missing or invalid authentication token |
403 | Forbidden | Authenticated but insufficient permissions |
404 | Not Found | Resource does not exist |
409 | Conflict | Duplicate record / unique constraint violated |
422 | Unprocessable Entity | Business logic validation failure |
500 | Internal Server Error | Unexpected server error |
Complete Examples
Example 1 — List with Pagination Only
GET /api/v1/users?limit=20&offset=20&sortBy=createdAt&sortOrder=ASC
Response:
{
"data": [
{
"id": 21,
"firstName": "Alice",
"lastName": "Smith",
"email": "alice@example.com"
},
{
"id": 22,
"firstName": "Bob",
"lastName": "Jones",
"email": "bob@example.com"
}
],
"pagination": {
"currentPage": 2,
"pageSize": 20,
"totalRecords": 58,
"totalPages": 3
}
}
Example 2 — Filtered + Sorted List
GET /api/v1/users
?limit=10&offset=0&sortBy=lastName&sortOrder=ASC
&filterQuery[rules][0][field]=isActive
&filterQuery[rules][0][operator]=eq
&filterQuery[rules][0][value]=true
&filterQuery[rules][1][field]=firstName
&filterQuery[rules][1][operator]=contains
&filterQuery[rules][1][value]=ali
Response:
{
"data": [
{ "id": 5, "firstName": "Alicia", "lastName": "Brown", "isActive": true },
{ "id": 9, "firstName": "Ali", "lastName": "Hassan", "isActive": true }
],
"pagination": {
"currentPage": 1,
"pageSize": 10,
"totalRecords": 2,
"totalPages": 1
}
}
Example 3 — Empty Result
GET /api/v1/organizations?limit=10&offset=0
&filterQuery[rules][0][field]=id
&filterQuery[rules][0][operator]=eq
&filterQuery[rules][0][value]=9999
Response:
{
"data": [],
"pagination": {
"currentPage": 1,
"pageSize": 10,
"totalRecords": 0,
"totalPages": 0
}
}
Example 4 — Create Organization
Request:
POST /api/v1/organizations
Content-Type: application/json
{
"organizationName": "Uniconnect Labs",
"email": "hello@uniconnect.io",
"phone": "+94112345678",
"countryId": 144,
"isActive": true
}
Response 201 Created:
{
"success": true,
"data": {
"id": 101,
"organizationName": "Uniconnect Labs",
"email": "hello@uniconnect.io",
"phone": "+94112345678",
"countryId": 144,
"isActive": true,
"createdAt": "2026-09-18T09:00:00.000Z",
"updatedAt": "2026-09-18T09:00:00.000Z"
},
"message": "Organization created successfully"
}
Example 5 — Validation Error
Request:
POST /api/v1/organizations
Content-Type: application/json
{
"email": "not-an-email"
}
Response 400 Bad Request:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "organizationName",
"message": "organizationName is required"
},
{ "field": "email", "message": "Must be a valid email address" }
]
}
}
Summary Checklist
- Use plural nouns and kebab-case for route paths
- Always return
data+paginationon list endpoints - Always return
success,data,messageon single-record endpoints - Use
limit/offsetfor pagination (notpage) - Expose
totalRecordsandtotalPagesin every paginated response - Use the
filterQuery[rules]structure for all filter parameters - Use appropriate HTTP status codes (
201for create,204for delete) - Wrap errors in
{ success: false, error: { code, message, details } } - Whitelist allowed sort fields server-side to prevent injection
- Validate filter fields against an allowed-fields list before querying