Skip to main content

Shared API Patterns and Guidelines

Overview​

This folder contains documentation on shared patterns, conventions, and best practices used across all Inventory Module APIs.

Common Patterns​

1. Soft Delete Strategy​

All entities in the inventory system use soft delete (archive/unarchive) instead of hard delete.

Pattern:

# Archive (soft delete)
DELETE /api/{resource}/{id}
Response: 204 No Content

# Unarchive (restore)
POST /api/{resource}/{id}/unarchive
Response: 204 No Content

# Get archived
GET /api/{resource}/archived
Response: 200 OK with archived entities

Benefits:

  • Maintains referential integrity
  • Preserves audit trail
  • Enables restoration
  • Supports compliance requirements

Implementation:

  • All entities have IsActive boolean flag
  • Archived entities: IsActive = false
  • Active entities: IsActive = true
  • Default queries filter to active only

2. Pagination Pattern​

Large result sets use consistent pagination across all APIs.

Pattern:

GET /api/{resource}?pageNumber=1&pageSize=50

Response:

{
  "items": [ /* ... */ ],
  "pageNumber": 1,
  "pageSize": 50,
  "totalCount": 234,
  "totalPages": 5,
  "hasPreviousPage": false,
  "hasNextPage": true
}

Guidelines:

  • Default pageNumber: 1 (1-based indexing)
  • Default pageSize: 50
  • Maximum pageSize: 200
  • Always include pagination metadata

3. Filtering Pattern​

Consistent query parameter filtering across all list endpoints.

Common Filters:

GET /api/{resource}?searchTerm=keyword&isActive=true&categoryId={guid}

Standard Filter Parameters:

  • searchTerm: Text search across key fields
  • isActive: Filter by active status (true/false/null for all)
  • {relation}Id: Filter by related entity (categoryId, locationTypeId, etc.)
  • dateFrom / dateTo: Date range filters
  • pageNumber / pageSize: Pagination

4. Error Response Format​

All APIs use RFC 7807 Problem Details format for errors.

Standard Error Response:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "errors": {
    "field1": ["Error message 1"],
    "field2": ["Error message 2"]
  }
}

Common Status Codes:

  • 200 OK: Successful GET/PATCH/PUT
  • 201 Created: Successful POST
  • 204 No Content: Successful DELETE or operation with no response body
  • 400 Bad Request: Validation errors, malformed request
  • 404 Not Found: Resource not found
  • 409 Conflict: Business rule violation, duplicate entity
  • 422 Unprocessable Entity: Domain logic violation
  • 500 Internal Server Error: Unexpected server error

5. Date/Time Format​

All date/time values use ISO 8601 format with UTC timezone.

Format: YYYY-MM-DDTHH:mm:ss.fffZ

Examples:

{
  "transactionDate": "2025-01-24T10:00:00.000Z",
  "createdDate": "2025-01-24T10:00:00.123Z",
  "modifiedDate": "2025-01-24T15:30:45.678Z"
}

6. GUID Format​

All entity IDs use GUIDs (UUID v4).

Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

7. Audit Fields Pattern​

All entities include standard audit fields.

Standard Fields:

{
  "id": "guid",
  "createdDate": "ISO 8601 datetime",
  "modifiedDate": "ISO 8601 datetime",
  "isActive": true/false
}

8. Hierarchical Path Display​

Entities in hierarchies include full path for display.

Examples:

  • Category Path: "Electronics > Computers > Laptops"
  • Location Path: "Main Warehouse / Zone A / Aisle 1"

Format:

{
  "fullPath": "Parent > Child > Grandchild",
  "separator": " > " // or " / " for locations
}

HTTP Methods and Semantics​

Standard CRUD Operations​

Create:

POST /api/{resource}
Status: 201 Created
Location: /api/{resource}/{new-id}

Read (Single):

GET /api/{resource}/{id}
Status: 200 OK

Read (List):

GET /api/{resource}
Status: 200 OK

Update (Full):

PUT /api/{resource}/{id}
Status: 200 OK

Update (Partial):

PATCH /api/{resource}/{id}
Status: 200 OK

Delete:

DELETE /api/{resource}/{id}
Status: 204 No Content

Custom Operations​

Use POST for non-CRUD operations:

POST /api/{resource}/{id}/unarchive
POST /api/{resource}/{id}/move
POST /api/transactions/assembly/assemble

Validation Patterns​

Required Fields​

{
  "errors": {
    "itemNumber": ["Item number is required."],
    "name": ["Name is required."]
  }
}

Format Validation​

{
  "errors": {
    "email": ["Invalid email format."],
    "quantity": ["Quantity must be greater than zero."]
  }
}

Business Rule Validation​

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8",
  "title": "Conflict",
  "status": 409,
  "detail": "An item with number 'WIDGET-001' already exists."
}

Versioning​

Currently, all APIs are version 1.0.

Future Versioning Strategy:

  • URL-based: /api/v2/{resource}
  • Header-based: Accept: application/vnd.inventory.v2+json
  • Maintain backwards compatibility for at least 2 versions

Security​

Authentication​

All API endpoints require authentication (implementation details TBD).

Authorization​

Role-based access control:

  • Read Operations: All authenticated users
  • Create/Update: Warehouse staff, supervisors
  • Delete/Archive: Supervisors, administrators
  • Configuration: Administrators only

Performance Guidelines​

Response Size Limits​

  • Maximum response size: 10 MB
  • Use pagination for large datasets
  • Consider summary DTOs for lists

Query Optimization​

  • Use selective field loading when possible
  • Implement caching for reference data
  • Use database indexes for filter fields

Best Practices​

  1. Always validate input before processing
  2. Use transactions for multi-step operations
  3. Publish events for cross-module integration
  4. Log errors comprehensively
  5. Return meaningful error messages
  6. Document breaking changes
  7. Version APIs when making breaking changes

Last Updated: 2025-10-24 | API Version: 1.0