feat: OpenAPI Specification for Middleware Management API

[keshxvdayal]

Design and document the complete REST API specification for middleware management operations using OpenAPI 3.0. This specification will define all endpoints, request/response schemas, error codes, and validation rules before any implementation begins.

[keshxvdayal]

Detailed Implementation Plan

1. Create OpenAPI Specification Document

   • Create data/specs/middleware_management.yaml
   • Define base paths and versioning (/ga4gh/tes/v1/middlewares)
   • Document all endpoints:
     • GET /middlewares - List all configured middlewares
     • POST /middlewares - Add new middleware (local or from GitHub)
     • GET /middlewares/{middleware_id} - Get middleware details
     • PUT /middlewares/{middleware_id} - Update middleware configuration
     • DELETE /middlewares/{middleware_id} - Remove middleware
     • PUT /middlewares/reorder - Reorder middleware stack
     • POST /middlewares/validate - Validate middleware code without adding
   • Define comprehensive schemas:
     • MiddlewareConfig - Full middleware configuration object
     • MiddlewareCreate - Request body for creating middleware
     • MiddlewareUpdate - Request body for updating middleware
     • MiddlewareList - Array response with pagination support
     • MiddlewareOrder - Order configuration for reordering
     • ValidationRequest - Code validation request
     • ErrorResponse - Standard error format
   • Document query parameters (pagination, filtering, sorting)
   • Define all possible HTTP status codes and error responses

2. Integrate with FOCA Configuration

   • Update pro_tes/config.yaml to reference the new spec
   • Add middleware API paths to FOCA routing configuration
   • Configure CORS and authentication settings (if applicable)
   • Set up request/response validation middleware via FOCA

3. Write API Documentation

   • Create docs/api/middleware_management.md
   • Provide usage examples with curl commands
   • Document authentication requirements
   • Explain order/priority system for middleware execution
   • Document fallback group behavior
   • Add sequence diagrams for complex operations (reordering, fallback)

4. Validation and Review

   • Validate OpenAPI spec with openapi-generator validate
   • Generate API documentation preview with Redoc/Swagger UI
   • Create examples for each endpoint operation
   • Peer review with team focusing on:
     • API design best practices
     • Consistency with existing proTES APIs
     • GA4GH TES specification alignment

Implementation completed in the feature/middleware-api-spec branch.

Branch: https://github.com/elixir-cloud-aai/proTES/tree/feature/middleware-api-spec
Commit: b8e0e74

Deliverables:

• OpenAPI 3.0 specification with 7 endpoints (pro_tes/api/middleware_management.yaml)
• FOCA integration configuration (pro_tes/config.yaml)
• Implementation documentation (docs/middleware.md)

All requirements from the issue have been addressed. Ready for review.