Callback

Overview
Configuration

Overview

Callback is primarily intended for simulating request/acknowledge/callback message exchange pattern:

API Simulator receives a request.
API Simulator replies with a response, for example, with status code 202 (Accepted) to acknowledge that the request was received. Any other status code can be returned, too, plus header fields, body, etc.
After an optional delay, API Simulator sends an HTTP/S request - callback - to some address. Usually, a correlation id is extracted from the original request and submitted along with the callback request so the receiver can correlate them.

Request/Acknowledge/Callback Message Exchange

Configuration

The callback request can be stubbed out or built dynamically from a template. This is completely independent from how the response to the original request was crafted.

API Simulator supports the HTTP/1.1 and HTTP/2 protocols for sending callback requests. For HTTP/2, API Simulator can connect to the callback server using all three methods: TLS with ALPN (Application-Layer Protocol Negotiation) extension, prior-knowledge (aka direct), or upgrade from HTTP/1.1.

Here are the configuration fields for a callback:

response:
  # ...

  callback:
    # The delay timer starts after the response is sent back. Optional.
    # Use any of the value distributions supported for response latency
    # (e.g. fixed, random, logNormal...)
    delay:
      # ...

    # One of the supported protocols:
    # http1: use http or https for URI scheme.
    # http2: HTTP/2 TLS with ALPN (https).
    # http2direct: aka HTTP/2 prior knowledge; clear text http.
    # http2upgrade: HTTP/2 upgrade from HTTP/1.1; clear text http.
    http1 | http2 | http2direct | http2upgrade:
      # "template" for dynamic, or "stub" for statically configured callback
      from: template | stub
      # Optional template kind when `from: template`
      template: Simula

      # Optional timeouts in milliseconds for the callback request
      timeouts:
        connect: <integer-number>
        read: <integer-number>

      # Any HTTP method/verb
      method: POST | PUT | GET | ...

      # Configure the URI by configuring its parts
      uri:
        # Required for http1, ignored for http2/http2direct/http2upgrade
        scheme: https | http

        # Use DNS name or IP address for host.
        # Don't include scheme, port number, path, query parameters, authority, or fragment
        host: "example.com"

        # If not configured, port will default to 80 for http and 443 for https
        port: 8080

        path: "/..."

        # Optional query string parameters
        query:
          # API Simulator will URL-encode the query string parameter's name and value
          - name: opts
            value: "4/5/6"

          # With this form, it is your responsibility to apply URL-encoding, if needed
          - "xyz=Yes"

          # It is your responsibility to URL-encode the query string parameter
          # This parameter will be added as having no value: "...&parm+1&..."
          - "parm+1"

          # API Simulator will URL-encode the query string parameter
          # This will be added as having empty value: "...&parm+2=&..."
          - name: "parm 2"

        # URI fragment added at the end of the URI after a '#', if configured
        fragment: ...

      headers:
          # "name: value(s)" format
        - "X-FOR-REQUEST-ID: ${ RequestID[0] }"
          # Separate name and value fields
        - name: Content-Type
          value: application/json

      # All options as for response body
      body: ...

See Simulating Latency for the various value distributions supported for a delay in submitting callback requests. Just replace in the configuration latency with delay.

The User-Agent header will default to the API Simulator version unless User-Agent header is explicitly configured.

The body of a callback request - text or binary - can be embedded in the simlet configuration as plain or base64-encoded text, come from an external file, or Parameter from File. Multi-line text surrounded by a pair of backtick characters without need to indent it per the YAML rules is also supported.

Consider that:

API Simulator will trust any and all certificates presented by the callback server.
No retries - API Simulator won’t resubmit a failed callback request (for example, if the attempt to establish a connection times out).
The response from the callback will simply be discarded.
Configuring and using proxies for the callback request is not currently supported.

We would love to hear your feedback - send us a quick email to [feedback at APISimulator.com]

Happy API Simulating!