318 319 320 321 api enhancements

[Xoulomon]

API Enhancements: Error Documentation, Versioning, Tracing, and Bulk Operations

Overview

This PR implements four critical API enhancements to improve error handling, maintainability, observability, and performance of the Atomic Patent API.

Changes Implemented

#318: Add API Error Code Documentation

• Created docs/api-error-codes.md with comprehensive error code reference
• Documented all HTTP status codes (400, 401, 404, 409, 422, 429, 500, 503)
• Provided recovery suggestions and common error scenarios for each status code
• Included unit and integration testing examples
• Added best practices for client-side error handling

#319: Implement API Versioning

• Created api-server/src/versioning.rs module with version negotiation middleware
• Added /v1/ prefix to all API endpoints for future compatibility
• Implemented Accept-Version header support for version negotiation
• Added API-Version response header to all responses
• Implemented deprecation warnings (Deprecation and Sunset headers)
• Updated all OpenAPI paths to use /v1/ prefix
• Added comprehensive tests for version negotiation and unsupported versions
• Updated Cargo.toml to include api-server in workspace

Supported Versions: 1.0.0 (current)

#320: Add API Request Tracing

• Created api-server/src/tracing_middleware.rs with OpenTelemetry-compatible tracing
• Added X-Trace-ID header support for distributed tracing across services
• Added X-Request-ID header for individual request tracking
• Implemented automatic trace ID generation and propagation
• Added request start/completion logging with duration metrics
• Integrated with existing tracing infrastructure
• Added comprehensive tests for trace ID generation and propagation

#321: Implement API Bulk Operations

• Added BulkCommitIpRequest and BulkCommitIpResponse schemas
• Added BulkInitiateSwapRequest and BulkInitiateSwapResponse schemas
• Added BulkOperationResult<T> generic schema for individual operation results
• Implemented POST /v1/bulk/commit-ip endpoint for batch IP commits
• Implemented POST /v1/bulk/initiate-swap endpoint for batch swap initiation
• Returns array of results with individual success/failure status for each operation
• Added validation for empty arrays and mismatched array lengths
• Added comprehensive tests for bulk operations

New API Endpoints

• POST /v1/bulk/commit-ip - Commit multiple IP records in one request
• POST /v1/bulk/initiate-swap - Initiate multiple swaps in one request

Files Modified

• docs/api-error-codes.md (new)
• api-server/src/main.rs (versioning, tracing, bulk routes)
• api-server/src/versioning.rs (new)
• api-server/src/tracing_middleware.rs (new)
• api-server/src/handlers.rs (bulk operation handlers, OpenAPI paths)
• api-server/src/schemas.rs (bulk operation schemas)
• api-server/Cargo.toml (added dependencies: uuid, reqwest, async-graphql, async-graphql-axum)
• Cargo.toml (added api-server to workspace)

Testing

All implementations include comprehensive tests:

• Error response format validation
• Version negotiation and unsupported version rejection
• Trace ID generation and propagation
• Bulk operation validation and result formatting

Middleware Stack (in order)

1. Tracing middleware - Adds trace IDs and request logging
2. Version negotiation - Validates API version
3. Metrics tracking - Records request metrics
4. Content-Type validation - Ensures JSON for POST/PUT/PATCH

Breaking Changes

• All endpoints now require /v1/ prefix (e.g., /ip/commit → /v1/ip/commit)

Backward Compatibility

• Version negotiation defaults to 1.0.0 if Accept-Version header is not provided
• Trace IDs are automatically generated if not provided in request

Documentation

• API error codes: docs/api-error-codes.md
• OpenAPI spec: /openapi.json
• Swagger UI: /docs

Closes

• Closes Add API Error Code Documentation #318
• Closes Implement API Versioning #319
• Closes Add API Request Tracing #320
• Closes Implement API Bulk Operations #321

[drips-wave]

@Xoulomon Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits