Test Execution API Endpoint

Overview

The Test Execution endpoint provides a mechanism for API publishers to test the SOAP-to-REST transformation of a specific API operation. It is an internal-only endpoint, primarily invoked by the "Test Operation" feature in the administration user interface.

This endpoint solves the problem of testing changes to an API's transformation logic in isolation. It allows for execution against draft or unpublished service versions, enabling iterative development and validation before a new version is published. It can also test operations for which a full OpenAPI specification has not yet been generated, using a synthetic schema derived from the underlying WSDL.

The endpoint receives a REST-style request, transforms it into a SOAP request, calls the backend SOAP service, processes the SOAP response, and returns a detailed JSON object that includes the raw SOAP messages, performance metrics, and a classification of the outcome.

How it Works

The Test Execution endpoint follows a multi-step process to execute a test and report its results. The entire outcome, whether successful or not, is typically wrapped in an HTTP 200 OK response containing a detailed JSON body.

flowchart TD
    A[API Consumer] --> B{Test Execution Endpoint};
    B --> C[1. Authenticate Request (JWT)];
    C -- Fails --> Z1[Return 401 Unauthorized];
    C -- OK --> D[2. Find Route Configuration];
    D -- Fails --> Z2[Return 404/500 Error];
    D -- OK --> E[3. Validate Request Body (JSON only)];
    E -- Fails --> F[Return 200 with Validation Report];
    E -- OK --> G[4. Transform REST to SOAP Request];
    G -- Fails --> H[Return 200 with Transformation Error];
    G -- OK --> I[5. Call Backend SOAP Service];
    I -- Transport Error --> J[Report Platform Error];
    I -- Success --> K[6. Parse SOAP Response];
    K -- Parse Fails --> J;
    K -- OK --> L[7. Classify Result];
    L -- SOAP Fault --> M[Report Backend Fault];
    L -- Applicative Error --> N[Report Applicative Error];
    L -- Success --> O[Report Success];
    subgraph "Final Response (HTTP 200 OK)"
        F
        H
        J
        M
        N
        O
    end
    J --> P[Assemble & Return Detailed JSON];
    M --> P;
    N --> P;
    O --> P;
    F --> P;
    H --> P;

1. Authentication: The endpoint first verifies the Authorization header. It expects a Bearer token containing an HMAC-signed JWT. The token's signature, expiration, audience (s2r-runtime-test-execute), and claims (versionId, operationKey) are all validated.
2. Route Resolution: It looks up the operation's configuration using the serviceVersionId and operationKey from the URL. This lookup is "draft-aware," meaning it can find and use configuration for service versions that have not yet been published.
3. Schema Validation: If the incoming request is JSON, its body is validated against the operation's OpenAPI schema. XML-based requests bypass this step. If validation fails, the process stops and returns a report of the violations.
4. SOAP Request Transformation: The incoming REST request is converted into a SOAP envelope. The endpoint handles three Content-Type variations:
   • application/json (or unspecified): The JSON body is transformed into a SOAP body based on the operation's mappings.
   • application/xml: The XML body is treated as a fragment and wrapped in a standard SOAP envelope.
   • text/xml: The body is assumed to be a complete SOAP envelope and is passed through as-is.
5. Backend SOAP Call: The generated SOAP request is sent to the configured backend endpoint URL.

   WARNING

   The test execution call does not use any configured backend credentials. The request is sent to the backend service without authentication. Retries are disabled for test calls.

6. SOAP Response Processing: The response from the backend is parsed. If the response is a valid SOAP Fault, it is flagged as such. If it's a successful response, it is transformed back into a JSON structure.
7. Error Origin Classification: The outcome of the entire process is classified into a single, machine-readable category (errorOrigin). This helps distinguish between validation errors, platform issues (e.g., timeouts), and errors originating from the backend.
8. Sample Persistence: For successful test runs (HTTP 200 from the backend, no SOAP fault), the request and response payloads are asynchronously saved. This data is used by the Spec Refinement service to suggest improvements to the API specification. This process is fire-and-forget and does not block or fail the test execution response.

API Reference

POST /_test/v1/{serviceVersionId}/{operationKey}

Executes a test run for a specific operation.

Path Parameters

Request Headers

Request Body

The request body's format is determined by the Content-Type header.

• application/json: A JSON object matching the operation's request schema.
• application/xml: An XML fragment representing the content of the SOAP <body>.
• text/xml: A full, valid SOAP envelope, including the <Envelope> element.

If the request body is empty, it is treated as an empty JSON object ({}) or an empty string for XML.

Response Body

The endpoint returns an HTTP 200 OK for most outcomes, with a detailed JSON body describing the result. Only critical, pre-flight failures (like invalid authentication) result in a non-200 status code.

Example Response Structure:

{
  "testMode": true,
  "schemaValidation": {
    "passed": true
  },
  "executionResult": {
    "latencyMs": 150,
    "rawSoapRequest": "...",
    "httpStatus": 200,
    "responseBody": {
      "field": "value"
    },
    "rawSoapResponse": "...",
    "soapFault": false
  },
  "errorOrigin": "SUCCESS",
  "errorDetail": {},
  "correlationId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
}

Top-Level Fields:

Schema Validation Object

This object reports the outcome of validating the incoming JSON request against the operation's schema.

A violation object has the following structure:

Execution Result Object

This object contains the details of the interaction with the backend SOAP service.

Error Origin Classification

The errorOrigin field provides a single, high-level category for the test outcome.

Authentication

Authentication is handled via a JSON Web Token (JWT) passed in the Authorization header.

• Format: Authorization: Bearer <token>
• Algorithm: The token must be signed using an HMAC-SHA algorithm.
• Key: The HMAC key is stored securely within the platform's secret store under the name TEST_EXECUTE_HMAC_KEY. A fallback to the S2R_TEST_EXECUTE_HMAC_KEY environment variable is supported for development or legacy configurations.
• Key Resolution: The HMAC key is resolved lazily on each request. If the key has not yet been provisioned in the secret store, the endpoint will return HTTP 503 Service Unavailable. Once the key is provisioned, subsequent calls will succeed without requiring a platform restart.
• Claims: The JWT payload must contain the following claims:
  • aud (Audience): Must be exactly s2r-runtime-test-execute.
  • versionId: Must match the serviceVersionId in the URL path.
  • operationKey: Must match the operationKey in the URL path.
  • exp (Expiration Time): Tokens are short-lived, with a typical TTL of 5 minutes.

Troubleshooting

The endpoint uses a combination of standard HTTP status codes for fatal errors and a detailed JSON body for test-run outcomes.

Non-200 HTTP Status Codes

These codes indicate a problem that prevented the test from running at all.

In-Body Error Codes

These codes appear within the executionResult or errorDetail objects in the 200 OK JSON response.

See Also

• Spec Refinement: Successful test executions contribute data to the automated spec refinement service.
• Applicative Error Markers: The APPLICATIVE_ERROR origin is determined by matching the SOAP response against configured error markers.

All SOAP-to-REST docs