API Adjustments For PraxOS Services

Welcome to an in-depth look at the crucial API adjustments we've made across several PraxOS services. Our primary goal has been to ensure that the runtime OpenAPI specifications for auth-service, notion-gpt-service, and whatsapp-service are not just functional, but also explicit, usable, and adhere to the highest standards. This means that GPT Actions can seamlessly interact with auth-service and notion-gpt-service, and whatsapp-service is perfectly configured for WhatsApp Cloud API webhook verification and event handling. We're focusing solely on the API contract, making changes only where necessary to align API behavior with the specification, ensuring a robust and predictable integration layer. Let's break down the specifics for each service and the overarching improvements.

auth-service: Fortifying the Authentication Contract

The auth-service plays a critical role in securing our platform, and ensuring its API contract is crystal clear is paramount. We've undertaken a series of specific adjustments to its OpenAPI specification to meet our stringent requirements. One of the most significant changes involves the servers definition. Each service's OpenAPI spec now explicitly includes a servers array, detailing the base URL. This is configured using the PUBLIC_BASE_URL environment variable, providing a flexible way to manage deployment environments. For local development, a default like http://localhost:<PORT> serves as a fallback, ensuring consistency whether you're developing locally or running in production. We've diligently documented this PUBLIC_BASE_URL handling in the relevant setup and local development guides, and crucially, added tests to assert that openapi.servers[0].url exists and is not empty. This proactive approach prevents runtime surprises and ensures clarity for any service or tool integrating with auth-service.

Furthermore, we've meticulously reviewed and refined the documented endpoints. For POST /v1/auth/device/start, we've ensured the request body schema is explicit, detailing the audience and scope parameters, and that the success response correctly outlines the device_code, user_code, verification_uri, verification_uri_complete, expires_in, and interval. The error responses, particularly for the 503 Service misconfigured scenario, now correctly reference the unified ApiError structure with explicit ErrorCode and message. Similarly, for POST /v1/auth/device/poll, the requestBody now clearly defines the mandatory device_code, and the success response accurately describes the access_token, token_type, expires_in, and id_token. The 409 Conflict response, indicating pending authorization, is also clearly defined with the appropriate error structure. We've also addressed the /v1/auth/refresh endpoint; if it exists, it's now fully documented with a clear requestBody requiring userId, and a precise success response detailing the refreshed tokens. If it didn't exist, it has been cleanly removed from the spec. The /v1/auth/config endpoint now provides a clear 200 response schema detailing domain, issuer, audience, and jwksUrl, crucial for understanding the authentication configuration. Endpoints like /health, /docs, and /openapi.json have also been standardized. Importantly, we've eliminated any instances of "Default Response" placeholders, ensuring every documented response is specific and actionable. Each operation now possesses a stable, unique operationId, and schemas are strict, using additionalProperties: false where appropriate and explicitly listing all required fields to prevent ambiguity. Security schemes are also accurate; auth-service endpoints that don't require bearer authentication are now correctly documented as public, enhancing the clarity of the API's security posture.

notion-gpt-service: Streamlining Notion and GPT Integration

The notion-gpt-service acts as a vital bridge between GPT capabilities and Notion data. To ensure seamless and predictable interactions, we've implemented significant OpenAPI adjustments. A core focus has been on refining the servers configuration, incorporating the PUBLIC_BASE_URL environment variable with a fallback to http://localhost:<PORT> for local development. This ensures that external services and internal tooling can reliably locate and communicate with the service, regardless of its deployment environment. We've also added tests to validate the presence and correctness of these server definitions in the openapi.json output. This meticulous attention to detail prevents integration issues and enhances the overall developer experience when working with the service.

We've rigorously updated the documented endpoints to be explicit and unambiguous, especially those geared towards GPT Actions. For POST /v1/integrations/notion/connect, the requestBody now precisely defines the notionToken and promptVaultPageId as required string fields, with clear descriptions. The success response schema explicitly details connected, promptVaultPageId, createdAt, and updatedAt. Similarly, GET /v1/integrations/notion/status and POST /v1/integrations/notion/disconnect have their request and response schemas clearly defined, including the use of bearer authentication. The securitySchemes for notion-gpt-service have been corrected; bearerAuth is now accurately described as a real JWT (JWKS) authentication, removing any mention of outdated stub authentication, which is crucial for security and clarity. This ensures that integrations requiring authentication understand the correct mechanism.

For the tools endpoints, such as GET /v1/tools/notion/promptvault/main-page and POST /v1/tools/notion/promptvault/note, we've ensured that the request and response schemas are explicit. The CreatePromptVaultNoteRequest schema now correctly uses additionalProperties: false and clearly lists title and prompt as required fields with specified length constraints. The corresponding CreatePromptVaultNoteResponse accurately defines pageId, url, and title. We've also confirmed that the canonical endpoint for creating notes is correctly documented, and any legacy alternatives have been removed. The /v1/webhooks/notion endpoint, while allowing a stub implementation, is now properly documented, ensuring clarity for potential implementers. As with auth-service, all "Default Response" placeholders have been eliminated from the OpenAPI specification. Every operation is guaranteed to have a stable, unique operationId, and response schemas are explicit, covering success (using the unified ApiOk<T> envelope) and relevant error scenarios (using ApiError with ErrorCode). Schemas themselves are kept strict, with required fields clearly listed and additionalProperties: false applied where appropriate to enforce data integrity. The /health, /docs, and /openapi.json endpoints are also standardized, ensuring consistency across the service's API surface.

whatsapp-service: Precision for WhatsApp Cloud API Integration

The whatsapp-service is our gateway for interacting with the WhatsApp Cloud API, and its API contract needs to be precise, especially for webhook verification and event handling. We've made targeted adjustments to its OpenAPI specification to ensure it meets these critical requirements. A fundamental change across all services, including whatsapp-service, is the explicit definition of servers in the OpenAPI output. We are utilizing the PUBLIC_BASE_URL environment variable to specify the base URL, with a fallback to http://localhost:<PORT> for local development. This guarantees that the webhook endpoints are correctly discoverable and accessible, whether in a development environment or a production setting. Tests have been added to verify that the servers array is present and correctly populated in the generated OpenAPI specification.

Our adjustments focused heavily on the webhook endpoints: GET /webhooks/whatsapp for verification and POST /webhooks/whatsapp for events. For the GET verification endpoint, a crucial change is ensuring the 200 response is documented as text/plain, returning the raw hub.challenge as required by WhatsApp, rather than a JSON object. This is a non-negotiable requirement for successful webhook verification. The parameters for this endpoint are clearly defined, including hub.mode, hub.verify_token, and hub.challenge. The POST /webhooks/whatsapp endpoint, designed to receive events, now has a clearly defined 200 response schema, typically indicating successful receipt, and appropriate error responses. We've also ensured that any requestBody for this endpoint, if applicable, is explicitly defined with its schema and required fields. As with the other services, all "Default Response" placeholders have been systematically removed from the whatsapp-service's OpenAPI specification. Each operation now has a stable and unique operationId, making it easier for consumers to reference specific API calls. The response schemas are explicit, differentiating between success (which, for event handling, might be a simple acknowledgment like ApiOk<T>) and various error conditions, using the standard ApiError structure where applicable. Schemas are kept strict, using required fields and additionalProperties: false to ensure data integrity and prevent unexpected input. The health, docs, and openapi.json endpoints are also standardized to align with the overall PraxOS API conventions. This meticulous refinement ensures that whatsapp-service adheres precisely to the WhatsApp Cloud API's expectations for webhook integration, providing a reliable and compliant interface.

Contract Tests and Deliverables: Ensuring Robustness and Compliance

To guarantee that our API adjustments are not only implemented but also consistently maintained, we've introduced a suite of contract tests for each service. These tests are designed to programmatically verify that the runtime OpenAPI specifications meet all the defined rules. The process involves booting each service's server using buildServer() and then using fastify.inject to make requests. Specifically, we call GET /openapi.json and assert several critical conditions. First, we confirm the complete absence of any "Default Response" strings within the serialized JSON output, ensuring that all documented responses are specific and informative. Second, we verify that every documented path and HTTP method combination has a stable, unique operationId, which is essential for predictable API consumption. Third, for every POST endpoint that accepts JSON, we assert that its requestBody is explicitly defined with a schema and the required flag. Fourth, for notion-gpt-service, we check that the bearerAuth security scheme's description accurately reflects JWT validation and does not mention any stub authentication mechanisms. Fifth, we specifically test the whatsapp-service's GET /webhooks/whatsapp endpoint to ensure its 200 response is documented as text/plain, as required for webhook verification. Finally, and crucially, we assert that the openapi.servers array exists and contains at least one valid, non-empty URL, confirming proper server configuration for all services.

Beyond the contract tests, our deliverables encompass the code changes required to implement these OpenAPI specifications correctly. This includes modifications to the swagger/openapi generation logic within each service's core files (apps/*/src/server.ts and apps/*/src/v1/routes.ts or schemas). We've also ensured that our documentation, including docs/architecture/api-contracts.md, is updated to reflect the actual, implemented API behavior, maintaining alignment between documentation and reality. The mandatory commands npm run format, npm run lint, npm run typecheck, npm run test:coverage, and npm run ci have all been successfully executed, confirming the code quality, adherence to standards, and build stability across the project. These comprehensive steps ensure that our API contracts are not just theoretical but are rigorously enforced through automated testing and maintainable code, providing a solid foundation for future development and integration.

Conclusion: A Clearer, More Reliable API Landscape

By undertaking these detailed API adjustments across auth-service, notion-gpt-service, and whatsapp-service, we've significantly enhanced the clarity, reliability, and usability of our service contracts. The meticulous refinement of OpenAPI specifications, particularly the explicit definition of servers, request bodies, responses, security schemes, and the elimination of vague placeholders, ensures that GPT Actions and other integrations can interact with our services with confidence. The introduction of robust contract tests provides an automated safety net, guaranteeing that these improvements are maintained over time. This commitment to a well-defined API contract is fundamental to building a scalable and maintainable ecosystem. For further insights into API best practices and OpenAPI specifications, you can refer to the OpenAPI Initiative website and the Swagger documentation.