Test Execution API Endpoint

Overview

The Test Execution endpoint is an administrative API that functions as a secure proxy to the platform's test execution runtime. It allows an authorized API publisher to invoke a specific API operation with a custom payload and receive a direct response from the backend system, as mediated by the runtime.

This endpoint solves the problem of providing a secure and convenient way to perform live integration tests. Instead of exposing the internal runtime test service, this endpoint validates the request, authenticates to the runtime using a short-lived, auto-provisioned credential, and forwards the request.

Key capabilities include:

• Secure Proxying: Authenticates to the runtime using a dynamically generated, HMAC-signed JSON Web Token (JWT).
• Automatic Key Provisioning: The HMAC secret key required for JWT signing is automatically generated and managed by the system, requiring no manual setup.
• Flexible Payload Support: Accepts JSON, XML, and full SOAP envelope payloads, preserving the Content-Type for the runtime to process correctly.
• Readiness Gate Integration: A successful test run against a live backend is automatically recorded as a valid test preview, which can satisfy publish-readiness requirements without needing a separate, generated test run.
• Auditing: All test executions are recorded in the audit log for traceability.

This endpoint is called by an API publisher, typically through a user interface, to manually test an operation's behavior before publishing it.

How it works

The test execution process involves a sequence of steps to securely proxy the request from the administrative environment to the runtime environment.

sequenceDiagram
    participant C as API Consumer
    participant P as Test Execution Proxy
    participant R as Test Execution Runtime
    participant DB as Platform Database

    C->>+P: POST /.../test-execute
    P->>P: Resolve runtime URL from request host
    P->>DB: Resolve HMAC key (read s2r_secret)
    alt Key not in DB
        P->>P: Check for legacy env var
        alt Env var exists
            P->>DB: Seed key into s2r_secret
            DB-->>P: Return seeded key
        else No env var
            P->>P: Generate 64-byte random key
            P->>DB: Seed key into s2r_secret (idempotent)
            DB-->>P: Return winning key
        end
    end
    DB-->>P: HMAC Secret Key
    P->>DB: Validate service/version/operation exist
    DB-->>P: Validation OK
    P->>P: Mint 5-minute JWT
    P->>+R: POST /_test/v1/... (with JWT)
    R-->>-P: Proxied Response (e.g., HTTP 200)
    P->>DB: Write audit log (best-effort)
    alt Successful Test Run
        P->>DB: Write to s2r_backend_test_preview (best-effort)
        DB-->>P:
    end
    P-->>-C: Return Proxied Response

The process flow is as follows:

1. Request Reception: The Admin API receives a POST request to the /admin/v1/services/{serviceId}/versions/{versionId}/operations/{operationKey}/test-execute endpoint.
2. Runtime URL Resolution: The system dynamically resolves the base URL of the target runtime service from the Host of the incoming request. This removes the need for static configuration.
3. HMAC Key Resolution: The HMAC secret key for signing the JWT is resolved lazily. This process is self-healing. See the HMAC Key Management section for details.
4. Input Validation: The system queries the database to confirm that the specified serviceId, versionId, and operationKey exist and are correctly associated with each other. If not, it returns a 404 Not Found error.
5. JWT Minting: A short-lived JWT is generated with a 5-minute time-to-live (JWT_TTL). It includes the versionId and operationKey as claims and is signed with the resolved HMAC key using the HS256 algorithm.
6. Request Forwarding: The system constructs a new POST request to the runtime's internal /_test/v1/{versionId}/{operationKey} endpoint.
   • The Authorization header is set to Bearer <jwt>.
   • The Content-Type header from the original request is preserved for XML/SOAP, or normalized to application/json for JSON payloads.
   • The request body is forwarded. JSON bodies are first parsed and normalized; XML/SOAP bodies are sent verbatim.
7. Response Passthrough: The response from the runtime (status code, headers, and body) is captured.
8. Auditing and Persistence: The system performs two best-effort actions that do not block or alter the response to the caller:
   • An audit event (service.test-execute-via-runtime) is recorded.
   • If the test was successful, a preview result is persisted to satisfy publish-readiness gates. See Readiness Gate Integration for details.
9. Return Response: The final response from the runtime is returned to the original caller. If the runtime response is not valid JSON, it is returned as text/plain.

HMAC Key Management

The security of the test execution proxy relies on an HMAC-signed JWT, which requires a shared secret key between the Admin API and the runtime. This key, identified as TEST_EXECUTE_HMAC_KEY, is managed automatically to ensure operational simplicity.

The key is resolved on the first test-execute call and cached in memory. The resolution follows a specific order:

1. Database (s2r_secret table): The system first attempts to retrieve the key from the s2r_secret table. This is the standard steady-state mechanism.
2. Environment Variable (S2R_TEST_EXECUTE_HMAC_KEY): If the key is not in the database, the system checks for a legacy environment variable S2R_TEST_EXECUTE_HMAC_KEY. If found, its value is immediately seeded into the s2r_secret table to be used for all subsequent lookups. This allows the environment variable to be retired after first use.
3. Auto-Generation: If neither the database nor the environment variable provides a key, the system generates a new, cryptographically secure 64-byte random key. It attempts to seed this key into the s2r_secret table using an idempotent INSERT ... ON CONFLICT DO NOTHING operation. It then re-reads the key from the database to ensure that in a concurrent environment, all service replicas converge on the single key that won the insertion race.

This self-healing mechanism ensures that a newly deployed system can become operational without any manual key provisioning steps.

Readiness Gate Integration

A primary feature of this endpoint is its integration with the publish-readiness gate. A successful manual test run provides valid evidence that an operation is configured correctly, and the system records this to satisfy the relevant readiness check.

A test run is recorded in the s2r_backend_test_preview table only if it meets all the following criteria:

• The runtime returns an executionResult object, indicating the backend was invoked.
• The httpStatus within the executionResult is 200.
• The schema validation outcome was not BLOCK.
• The response from the backend is not a SOAP Fault. The system uses the SoapMessageMapper to parse the response and detect faults.
• The runtime did not classify the response as an applicative error (i.e., the errorOrigin field in the runtime response is NONE or absent).

If these conditions are met, a record with overall_status='ok' is created. If the backend returns an HTTP 200 response but contains a SOAP Fault or a classified applicative error, the run is recorded with overall_status='failed' and will not satisfy the readiness gate. This ensures that only truly successful interactions are counted.

API Endpoint Reference

Execute a Test Run

Proxies a test request for a specific operation to the runtime environment.

POST /admin/v1/services/{serviceId}/versions/{versionId}/operations/{operationKey}/test-execute

Path Parameters

Request Body

The request body is optional and its content depends on the Content-Type header.

• application/json: The body should be a valid JSON object. If the body is empty or omitted, it is treated as an empty JSON object ({}). The system validates the JSON structure before proxying.
• application/xml or text/xml: The body should be a valid XML or SOAP document. The body is proxied to the runtime verbatim without validation by the proxy.

The source does not provide a concrete example request payload.

Responses

• 2xx/4xx/5xx: The endpoint proxies the HTTP status code and response body directly from the downstream runtime service. If the runtime response is valid JSON, the Content-Type will be application/json. Otherwise, it may be text/plain.
• Error Responses: If the proxy itself encounters an error before calling the runtime, it will return a structured JSON error.

Example Error Response

{
  "error": {
    "code": "S2R-ADM-0404",
    "message": "service not found",
    "correlationId": "f8c3de3d-1fea-4d7c-a8b0-29d6a2a044e1",
    "time": "2023-10-27T10:00:00Z"
  }
}

Configuration

The endpoint's behavior is primarily configured through the database. However, it supports one environment variable for backward compatibility and initial seeding of the HMAC key.

Troubleshooting

The following are common errors originating from the test execution proxy itself. Errors from the downstream runtime will be passed through.

Internal system logs contain more detailed error information, correlated by the X-Correlation-Id header. Look for log messages with codes like S2R-ADM-0423 and S2R-ADM-0502.

All SOAP-to-REST docs