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

        # Host can be a DNS name or an IP address
        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 except body from a file
      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.

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.
A file as source for the callback request body is not currently supported. Notice that it is still possible to use Parameter from File for a text body.

We would love to hear your feedback! Shoot us an email to [feedback at APISimulator.com] about anything that is on your mind.

Happy API Simulating!