Response HTTP Codec


HTTP Codec configuration settings control certain aspects of simulated stubbed or dynamic responses.

Probably the ones you would use more frequently are those for configuring the transfer encoding and content encoding of a response. For a practical example, see also Large File Download Example.


    # Specifies if the connection with the client is to be always
    # closed after returning the response even when the client may
    # have asked for 'keep-alive' connection. Defaults to 'false'.
    alwaysCloseConnection: true | false

    # The transfer encoding to apply to the content and set as
    # value in "Transfer-Encoding" header if the response doesn't
    # already have a non-empty "Transfer-Encoding" header.
    # If the response's content is compressed (i.e. gzip/deflate
    # encoded), then "chunked" transfer encoding is applied
    # automatically.
    # Note that this has no effect when the protocol is HTTP/2.
    transferEncoding: 'chunked'

    # The encoding to apply to the content and set as value in
    # "Content-Encoding" header. The content encoding, per the
    # HTTP 1.1 spec, is related to applying 'gzip' or 'deflate'
    # compression. The encoding will be applied only if the request
    # specifies that the client does accept that encoding and if the
    # content isn't already encoded/compressed.
    contentEncoding: 'gzip' | 'deflate'

    # The server name to set as a "Server" header. Use it to pretend
    # that the response is returned from a particular server.
    # Defaults to the version of API Simulator in use.
    serverName: 'MyPretendServer'

    # When a "Date" header is missing, value of 'true' (the default)
    # instructs API Simulator to set a "Date" header with the current
    # date and time formatted per the HTTP spec.
    # When the value is 'false' then no 'Date' header will be added
    # even if it is missing.
    setDateWhenMissing: true | false

    # When "Date" header is already present, value of 'true' will cause
    # a "Date" header with the current date and time formatted per the
    # HTTP spec to be set and override the existing "Date" header.
    # Default is 'false'.
    setDateWhenPresent: false | true

    # The maximum acceptable length of the initial HTTP (status)
    # line in a response (e.g. "HTTP/1.0 200 OK").
    maxInitialLineBytes: 1024

    # The maximum acceptable total size of all headers in a response,
    # in bytes. That includes the header delimiters CRLF (0x13, 0x10).
    maxHeaderBytes: 8192

    # The maximum size of each content chunk in bytes. This setting
    # only matters when the response is transfer encoded as 'chunked'.
    maxChunkBytes: 10240

    # The maximum length of aggregated response content in bytes.
    # This setting only matters if the response is accumulated all
    # in memory to calculate and set Content-Length HTTP header.
    maxContentBytes: ...

Large File Download Example

Even though API Simulator is not an optimized file server, it provides very good support for simulating the downloading of large files. And by saying large files we mean even files as big as tens of gigabytes! Not only that but API Simulator would be running with only few megabytes of memory, all thanks to the use of streaming at its core.

It is important to configure the transfer encoding and content encoding settings in the response HTTP codec to simulate how file servers serve large files over HTTP/S.

Here is an example simlet:

# GET /downloads?fileId=<file-id>
- method: GET
- uriPath: /downloads
- where: uriQueryParameter
  named: "fileId"
  equals: "<file-id>"

  from: stub

    transferEncoding: chunked
    contentEncoding: deflate

  status: 200
    - "Content-Type: application/octet-stream"

    type: binary
      path: "<absolute-path-to-the-file>"
      name: "<file-name>"
    # Disable in-memory caching for large files or may run out of memory
    cacheFile: false

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

Happy API Simulating!