1. Home
  2. Tyk API Gateway v1.9
  3. API Management
  4. API Definition Objects

API Definition Objects

Tyk handles APIs through files / objects called Definitions, these either sit in the /etc/tyk/apps directory or in a MongoDB collection.

An API Definition has many switches that change the way an incoming request is handled. It is possible to set too many options in a defintiton which can lead to unexpected behaviour.

With this in mind, we have split this section into the most common settings that are used together.

Common elements

id

This is only used in the MongoDB context and bears no actual relation to the identity of the API

name

Human readable name of the API, is used for identification purposes but does not act as an index.

api_id

The identifier for the API, this should be unique, but can actually be any kind of string. for single-instance setups this can probably be set to 1. It is recommended to make this a UUID.

The api_id is used when querying the Tyk REST API for configuration details.

org_id

This is an identifier that can be set to indicate ownership of an API key or of an individual API.

If the the Org ID is set (recommended), it is prepended to any Keys generated by Tyk – this enables lookups by prefixes from redis of keys that are in the system.

active

If set to false means that on start, restart or reload the API will be ignored and all paths and routes for that API will cease to be proxied. Any keys assigned to it will still exist, though they will not be let through for that particular API.

session_lifetime

The session lifetime will override the expiry date if it has been set on a key (in seconds). for example, if a key has been created that never expires, then it will remain in the
session cache forever unless manually deleted. If a re-auth needs to be forced or a default expiry needs to be applied to all keys, then use this feature to set the session
expiry for an entire API.

Authentication type flags

By default, Tyk will revert to a simple authentication token scheme unless these flags and their metadata are set (setting all of these to false will enable standard token mode).

This scheme basically means that you could send an authentication parameter and it’s value (the api key) along with the request and Tyk will attach it to a session, just like a bearer token in OAuth or a session key in cookie-based setups.

However Tyk supports many more methods, and these can be set by enabling these flags (and their associated metadata)

use_keyless

This will switch off all key checking and open the API definition up, some analytics will still be recorded, but rate-limiting, quotas and security policies will not be possible (there is no session to attach requests to).

this is a good setting for checking if Tyk works and is proxying traffic correctly.

This method has no additional metadata settings

use_basic_auth

This method will enable basic auth as specified by the HTTP spec, an API with this flag set will request for a username and password and require a standard base64 Authentication header to be let through.

Keys cannot be generated by Tyk for this method and need to use the /tyk/keys/add method with the basic_auth_data metadata set in the keys session configuration (see Basic Authentication and the overview of the Session Object in this use case under Key Management).

enable_signature_checking a.k.a HMAC signing

If this option is set to true, Tyk will attempt to implement the HMAC singing standard as proposed in the HTTP Signatures Spec. In particular the structure of the Authorisation header and the encoding method need to be taken into account.

This method will use a session key to identify a user and a user secret that should be used by the client to sign each request’s date header.

This method will also introduce clock skew checks, requests outside of 300ms of the system time will be rejected.

This method is not recommended for Single-Page-Webapps or Mobile apps due to the fact that secrets need to be distributed.

hmac_allowed_clock_skew

Set this value to anything larger than 0 to set the amount of milliseconds that will be tolerated for clock skew. Set to 0 to prevent clock skew checks on requests (only in HMAC mode).

use_oauth2

Tyk attempts to implement a semi-seamless OAuth2 flow. Given the nature of OAuth2’s three-party system, it is difficult to implement as a proxy without significantly compromising security or usability.

Enabling this option will cause Tyk to add OAuth2-standard endpoints to the API for /authorize and /token, these will supersede any other requests to your proxied system in order to enable the flow.

Please see the OAuth2 Flow section for a comprehensive discussion of how to integrate with Tyk.

oauth_meta.allowed_access_types

Should be a string array of OAuth access options, types can be:

  • authorization_code – client has an authorisation code to request a new access token
  • refresh_token – client can use a refresh token to refresh expired bearer access token

Note: If using auth codes and refresh tokens, Tyk needs to notify your webapp of newly issued keys – it does this via web hook, please see the section on notifications.

oauth_meta.allowed_authorize_types

Should be a string array of OAuth authorisation types – options that are supported are:

  • code – Client can request an authorization code which can be used to request an access code via a server request (traditionally reserved for server-side apps)
  • token – Client can request an access token directly, this will not enable refresh tokens and all tokens have a 12 hour validity. Recommended for mobile apps and single-page webapps.

oauth_meta.auth_login_redirect

The Tyk OAuth flow has a dummy (intercept) /authorize endpoint which basically redirects the user to your login and authentication page, it will also send along all OAuth data as part of the request (so as to mimic a regular app flow).

This is the URL that the user will be sent to (via POST).

Note: This interface method is only supported by modern browsers that respect a 307 redirect (retaining method and data), and varies between browsers.

notifications

When Tyk implements an OAuth2 flow, because it will handle access requests on your behalf once auth codes have been issued, it will need to notify your system that these have occurred.

It will POST key data to the URL set in these options to ensure that your system is synchronised with Tyk.

notifications.shared_secret

POSTED data to your service will use this shared secret as an authorisation header, this is to ensure that messages being received are from Tyk and not from another system.

notifications.oauth_on_keychange_url

The URL that will be sent the updated information – the URL will be polled up to 3 times if there is a communications failure. On a 200 OK response it stops.

auth

The auth section handles the standard Tyk authentication method, and if none of the above are set, will be the method used to authenticate requests.

auth.use_param

This will force Tyk to look for the auth_header_name value in the URL querystring parameters instead of in the header.

auth.use_cookie

This will force Tyk to look for the auth_header_name value in a cookie.

auth.auth_header_name

The header carrying the authentication token. Currently parameter-based authentication token passing is not supported.

Versioning and Endpoint Handling

Tyk lets you version your API and apply access policies to versions, for example, if you have an API v1 that has a /widgets endpoint that is deprecated in v2, you can blacklist that endpoint so that requests to it are stopped before they hit your system.

In the same vein, you can white-list and ignore paths completely.

Version data can be transferred as either a header key or as a query parameter in all HTTP methods.

definition

This section handles information related to where to look for the version key

definition.location

Can either be:

  • header: Tyk will look for the version information in a header field (e.g. api-version: 1.2.3)
  • url-param Tyk will check form and request parameters for a key matching the definition.key value.

definition.key

The name of the key to check for versioning information.

version_data

Information relating to your actual version are stored here, if you do not wish to use versioning, use the not_versioned option and set up an entry called Default (see below).

version_data.not_versioned

If set to true Tyk will skip version checking, you can still apply blacklist and white-list information to your API by specifying a Default version within the versions map

version_data.versions

This is a keyed JSON object, in the form of:

{
    "version-1": {
        "name": "version-1",
        "expires": "",
        "paths": {
            "ignored": [],
            "white_list": [],
            "black_list": []
        },
        "use_extended_paths": true,
        "extended_paths": {
            "ignored": [],
            "white_list": [],
            "black_list": []
        }
    }
}

Each version of your API should be defined here with a unique name, this name is what will be matched by defintition.key. Once Tyk has identified the API to load, and has
allowed the access key through, it will check the access token’s session data for access permissions. If it finds none, it will let the token through, however if there are
permissions and versions defined, it will be strict in only allowing access to that version. For more information about handling access control, please see the
access control section.

version_data.{version-name}.expires

The expires header, if set, will deprecate access to the API after the time specified. The entry here takes the form of: "YYYY-MM-YY HH:MM". If this is not set the version will never expire.

version_data.{version-name}.ignored (legacy – deprecated)

This string array can define any paths (endpoints) in your API that should be ignored by Tyk, for example login, signup
or any non-authenticated actions users can take. Specify these URL’s here in the form of

[
    "/user/login",
    "/user/signup"
]

Similar to other routers, matching is done on a first-come-first-served basis, ensure that specific paths are higher up the list than generic ones.

Note: It is possible to ignore non-generic paths using standard REST documentation markup, e.g. /users/{user_id}/ will ignore /users/12345/ and /users/jively, this is handy for cases where an entire sub-branch of a resource should be ignored (though each wildcard must be specified individually) Parameter names are arbitrary, and should be for reference only.

version_data.{version-name}.white_list (legacy – deprecated)

A string array of paths to white-list in your API, this is an explicit list of paths that are allowed access, any other endpoints, except those specified in
ignored_paths will be refused access. Use this to enforce highly-specific access rules.

Note: White listing paths is exclusive, so black listed paths will not take effect.

version_data.{version-name}.black_list (legacy – deprecated)

The opposite of white_list, this will essentially block access to certain endpoints, this can be very handy if you are moving from a v1 to a v2 and have deprecated a path, simply define the deprecated
path in the list and requests to it ith the new version header will be refused.

version_data.{version-name}.use_extended_paths

Set this value to true to use the new extended-paths feature, this will eventually become the default mode of operation.

Extended paths allow you to control which upstream paths are to be handled in a specific way (ignored, as part of white
list or black list) by both path and method. The extended meta-data set also allow you to provide forced reply data to override
or trap inbound requests for specific versions. This is very useful for mocking or slowly exposing a development API to a live
upstream back end.

Each entry in the ignored, black and white list lists have the same specification. The path specification
has the following format:

{
    "path": "{managed-path}",
    "method_actions": {
        "METHOD": {
            "action": "{action-code}",
            "code": {response-code},
            "data": "{body}",
            "headers": {
                "{key}": "{value}"
            }
        }
    }
}

You can set up the path to handle, and the action type, by default this should be set to no_action which means that Tyk will
treat the path and method as-is without interference (i.e. if no_action is set, then code, data, headers and body are not used).

If you set action to reply Tyk will override the path and reply with settings defined in the remaining fields. This configuration can be
used across all of the different path lists, and can be very useful when used in conjunction with the white_list access control list as
If it is used exclusively it can be used to mock out an entire API.

**Note: ** Any data that is placed in the ‘data’ section must be a string, not a JSON object (this could be a JSON string, for example).

global_headers

Set global headers to inject using a key:value map:

"version_data": {
    "versions": {
      "Default": {
        ...
        "global_headers": {
            "x-header-name": "x-header-value"
        }
        ...
      }
    }
},

global_headers_remove

Remove headers from all requests:

"version_data": {
    "versions": {
      "Default": {
        ...
        "global_headers_remove": [
            "auth_id"
        ]
        ...
      }
    }
},

global_size_limit

Set a global request size limit in bytes

version_data.{version-name}.extended_paths.size_limits

version_data.{version-name}.extended_paths.ignored

This section will define methods and paths that will be ignored and will bypass the quota and rate limiting machinery of Tyk.

An example entry:

...
"ignored": [
    {
        "path": "/v1/ignored/literal",
        "method_actions": {
            "GET": {
                "action": "no_action",
                "code": 200,
                "data": "",
                "headers": {}
            }
        }
    },
    {
        "path": "/v1/ignored/with_id/{id}",
        "method_actions": {
            "GET": {
                "action": "reply",
                "code": 200,
                "data": "Hello World
",
                "headers": {
                    "x-tyk-override": "tyk-override",
                }
            }
        }
    }
], ...

version_data.{version-name}.extended_paths.black_list

This section defines methods and paths that will be blocked by Tyk.

An example entry:

...
"black_list": [
    {
        "path": "v1/disallowed/blacklist/literal",
        "method_actions": {
            "GET": {
                "action": "no_action",
                "code": 200,
                "data": "",
                "headers": {}
            }
        }
    },
    {
        "path": "v1/disallowed/blacklist/{id}",
        "method_actions": {
            "GET": {
                "action": "reply",
                "code": 200,
                "data": "Not allowed buddy 
",
                "headers": {
                    "x-tyk-override-test": "tyk-override"
                }
            }
        }
    }
], ...

version_data.{version-name}.extended_paths.white_list

This section defines methods and paths that are exclusively allowed through by Tyk. Use this section to
define an entire mock API as well as this will force a specific URL structure (and block all other paths)
while replying to all requests, therefore never sending any requests upstream.

An example entry:

...
"white_list": [
    {
        "path": "v1/allowed/whitelist/literal",
        "method_actions": {
            "GET": {
                "action": "no_action",
                "code": 200,
                "data": "",
                "headers": {}
            }
        }
    },
    {
        "path": "v1/allowed/whitelist/reply/{id}",
        "method_actions": {
            "GET": {
                "action": "reply",
                "code": 200,
                "data": "flump  
",
                "headers": {
                    "x-tyk-override-test": "tyk-override"
                }
            }
        }
    },
    {
        "path": "v1/allowed/whitelist/{id}",
        "method_actions": {
            "GET": {
                "action": "no_action",
                "code": 200,
                "data": "",
                "headers": {}
            }
        }
    },
    {
        "path": "/tyk/rate-limits/",
        "method_actions": {
            "GET": {
                "action": "no_action",
                "code": 200,
                "data": "",
                "headers": {}
            }
        }
    }
], ...

You’ll notice we’ve included the end user rate-limit check URL as a white listed path, if you don’t do this,
Tyk will block access to this URL.

version_data.{version-name}.extended_paths.cache

If the cache is enabled (see cache_options), then these paths will be cached. Caching is applied on all sae methods (GET, OPTIONS and HEAD), caching cannot be controlled on a per-method basis.

A sample entry would be:

...
"cache": [
    "widgets/{widgetID}",
    "widgets",
    "foobars/{foobarID}",
    "foobars"
], ...

version_data.{version-name}.extended_paths.transform and version_data.{version-name}.extended_paths.transform_response

This section determines which paths are to have a template applied to them in order to transform the body data in the request or response to another structure. Currently on JSON body data is supported as
an input, however the template can output to any format, as it uses Golang templates so structure of outbound data is highly configurable.

...
"transform": [
    {
        "path": "widget/{id}",
        "method": "POST"
        "template_data": {
            "template_mode": "file",
            "template_source": "./templates/transform_test.tmpl"
        }
    }
], ...

All the settings that apply to request transforms also apply to response transforms.

version_data.{version-name}.extended_paths.transform.path

This is the path to apply the template to.

version_data.{version-name}.extended_paths.transform.method

This is the method to apply the template to

version_data.{version-name}.extended_paths.transform.template_data.template_mode

Can be either file or blob. Setting this to file will have Tyk try to load the path and parse the template from a file set in template_source. Setting this to blob enables the template to be
embedded in the definition, e.g. if Tyk is pulling configurations from a database. Embedded templates must be Base64 encoded strings and placed in the template_source field.

version_data.{version-name}.extended_paths.transform.template_data.template_source

The file, or base64-encoded lob that will be used as a template to perform the transformation.

version_data.{version-name}.extended_paths.transform_headers and version_data.{version-name}.extended_paths.transform_response_headers

Elements specified in this list will have their headers modified according to the rules set out in the path meta settings. These settings are the same for both request and response headers.

Entries look like this:

"transform_headers": [
    {
        "delete_headers": ["Content-Type", "authorization"],
        "add_headers": {"x-tyk-test-inject": "new-value"},
        "path": "widgets/{id}",
        "method": "GET"
    }
]

version_data.{version-name}.extended_paths.transform_headers.delete_headers

Tyk will remove these headers from a request if it is processed.

version_data.{version-name}.extended_paths.transform_headers.add_headers

Tyk will add the headers and values specified in this list, deletions happen before additions, so modifying headers that already exist is possible by specifying the same key in delte and add.

version_data.{version-name}.extended_paths.transform_headers.path

The path that the header injection will be applied to

version_data.{version-name}.extended_paths.transform_headers.path

The method for this path that the injection will be applied to.

version_data.{version-name}.extended_paths.hard_timeouts

This section enables you to set hard timeouts on a path-by-path basis, e.g. if you have a long-running microservice, but do not want to hold up a dependent client should a query take too long, you can enforce a timeout for that path so the requesting client is not held up forever.

```
 ...
 extended_paths: {
      ...
      hard_timeouts: [
        {
          path: "delay/5",
          method: "GET",
          timeout: 3
        }
      ]
}
...
```

The path and method properties are the same as all the other extended path middleware settings.

version_data.{version-name}.extended_paths.hard_timeouts.timeout

Set this value to the number of seconds that the hard-timeout should respect. Hard timeout can behave strangely, especially with HTTP 1.1 connections where TCP connections stay open, a client will often retry- a call if it times out. The way to fix this is to configure the node to use the close_connections setting in it’s configuration file.

version_data.{version-name}.extended_paths.circuit_breakers

This section defines whether a path should act as a circuit breaker against the upstream proxy. Our circuit breaker is threshold-based, so if x% of requests are failing then the circuit is tripped. When the circuit is tripped, then the gateway will stop all inbound requests to that service for a pre-defined period of time (a recovery time-period).

The circuit breaker will also emit an event which you can hook into to perform some corrective or logging action.

The path and method properties are the same as all other extended_path middleware actions

```
"circuit_breakers": [
    {
      "path": "get",
      "method": "GET",
      "threshold_percent": 0.5,
      "samples": 5,
      "return_to_service_after": 60
    }
  ]
```

version_data.{version-name}.extended_paths.circuit_breakers.threshold_percent

The threshold to use for triggering an event, in this case it is between 0 and 1, with 1 being 100% of requests.

version_data.{version-name}.extended_paths.circuit_breakers.samples

The number of samples to apply the threshold to, so x%`` ofy` samples will trip the circuit.

version_data.{version-name}.extended_paths.circuit_breakers.return_to_service_after

The number of seconds to take the path offline, once this time limit is up, the breaker is reset and the service comes back online.

version_data.{version-name}.extended_paths.url_rewrites

Tyk has suport for rudimentary URL rewrites, this will enable you to modify inbound URLs to ones that your service understands. The URL rewrite section takes a similar form to other extended paths, with a bit of quirk.

Tyk will match the path element, like any other path in the extended paths section, here you can use wildcards such as widgets/{id} to show that anything should match.

However, it is important to remember that wildcards like this {id} actually get converted to (.*) regexes, and are not extracted, they are thrown away and are ONLY used for matching the path to trigger the middleware.

The transform is handled by the other two options, which can use any valid regex to group parameters:

```
"url_rewrites": [
    {
      "path": "virtual/{wildcard1}/{wildcard2}",
      "method": "GET",
      "match_pattern": "virtual/(.*)/(d+)",
      "rewrite_to": "new-path/id/$2/something/$1"
    }
  ]
```

version_data.{version-name}.extended_paths.url_rewrites.match_pattern

This is the match pattern to use to extract parameters from the URL

version_data.{version-name}.extended_paths.url_rewrites.rewrite_to

This is the path structure to rewrite to, use $1, $2, $n to specify which group to reference in the new URL.

version_data.{version-name}.extended_paths.virtual

This section specifies the paths that should execute a “virtual” path, i.e. execute a blob of javascript to perform some kind of function in the API, these can be anything from mock responses to aggregates. Because this section is quite large, we have created a dedicated “Virtual Paths” page under the “Api Management” section.

proxy

The proxy section outlines the actual API proxying functionality, here you can define where Tyk should listen, and where Tyk should proxy traffic to.

proxy.listen_path

The path to listen on, e.g. /api or /, any requests coming into the host, on the port that Tyk is configured to run on, that go to this path will have the rules
defined in the API Definition applied. Versioning assumes that different versions of an API will live on the same URL structure. If you are using URL-based versioning
(e.g. /v1/function, /v2/function/ then it is recommended to set up a separate non-versioned Definition for each version as they are essentially separate APIs.

Proxied requests are literal, no re-writing takes place, for example, if a request is sent to the listen path of: /listen-path/widgets/new and the URL to proxy to is
http://your.api.com/api/ then the actual request that will land at your service will be: http://your.api.com/api/listen-path/widgets/new.

this behaviour can be circumvented so that the listen_path is stripped from the outgoing request. See the section on strip_listen_path below.

proxy.target_url

This defines the target URL that the request should be proxied to if it passes all checks in Tyk.

proxy.enable_load_balancing

Set this value to true to have a Tyk node distribute traffic across a list of servers. **Required: ** You must fill in the target_list section.

proxy.target_list

A list of upstream targets (can be one or many hosts)

proxy.service_discovery

The service discovery section tells Tyk where to find information about the host to proxy to. In a clustered environment this is useful if servers are coming online and offline dynamically with new IP addresses. The service discovery module can pull out the required host data from any service discovery tool that exposes a RESTful endpoint that outputs a JSON object.

```
"enable_load_balancing": true,
service_discovery: {
  use_discovery_service: true,
  query_endpoint: "http://127.0.0.1:4001/v2/keys/services/multiobj",
  use_nested_query: true,
  parent_data_path: "node.value",
  data_path: "array.hostname",
  port_data_path: "array.port",
  use_target_list: true,
  cache_timeout: 10
},
```

proxy.service_discovery.use_discovery_service

Set this to true to enable the discovery module

proxy.service_discovery.query_endpoint

The endpoint to call

proxy.service_discovery.data_path

The namespace of the data path, so for example if your service responds with:

```
{
    "action": "get",
    "node": {
        "key": "/services/single",
        "value": "http://httpbin.org:6000",
        "modifiedIndex": 6,
        "createdIndex": 6
    }
}
```

Then your name space would be node.value.

proxy.service_discovery.use_nested_query

Sometimes the data you are retrieving is nested in another JSON object, e.g. this is how Etcd responds with a JSON object as a value key:

```
{
    "action": "get",
    "node": {
        "key": "/services/single",
        "value": "{"hostname": "http://httpbin.org", "port": "80"}",
        "modifiedIndex": 6,
        "createdIndex": 6
    }
}
```

In this case, the data actually lives within this string-encoded JSON object, so in this case, you set the use_nested_query to true, and use a combination of the data_path and parent_data_path (below)

proxy.service_discovery.parent_data_path

This is the namespace of the where to find the nested value, in the above example, it would be node.value.

You would then change the data_path setting to be hostname.

Tyk will decode the JSON string and then apply the data_path namespace to that object in order to find the value.

proxy.service_discovery.port_data_path

In the above nested example, we can see that there is a separate PORT value for the service in the nested JSON. In this case you can set the port_data_path value and Tyk will treat data_path as the hostname and zip them together (this assumes that the hostname element does not end in a slash or resource identifier such as /widgets/).

In the above example, the port_data_path would be port.

proxy.service_discovery.use_target_list

If you are using load_balancing, set this value to true and Tyk will treat the data path as a list and inject it into the target list of your API Definition.

proxy.service_discovery.cache_timeout

Tyk caches target data from a discovery service, in order to make this dynamic you can set a cache value when the data expires and new data is loaded.

proxy.strip_listen_path

By setting this to true, Tyk will attempt to replace the listen_path in the outgoing request with an empty string – this means that in the above scenario where
/listen-path/widgets/new and the URL to proxy to is http://your.api.com/api/ becomes http://your.api.com/api/listen-path/widgets/new, actually
changes the outgoing request to be: http://your.api.com/api/widgets/new.

proxy.check_host_against_uptime_tests

If uptime tests are enabled, Tyk will check the hostname of the outbound request against the downtime list generated by the host checker, if the host is found, then it is skipped.

IP White-listing (Middleware)

enable_ip_whitelisting

If set to true, only requests coming from the explicit list of IP addresses (allowed_ips) are allowed through.

allowed_ips

A list of strings that defines the IP addresses that are allowed access via Tyk. This list is explicit and wildcards are currently not supported. e.g.:

...
"enable_ip_whitelisting": true,
"allowed_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14"]
...

Batch Requests

Tyk now supports request batching, so a client only makes a single request to the API but gets a compound response object back.

To enable batch-request support, set the enable_batch_request_support value to true

This is especially handy if clients have complex requests that have multiple synchronous dependencies and do not wish to have the entire request / response cycle
running for each event.

Batch requests that come into Tyk are run through the whole Tyk machinery and use a relative path to prevent spamming, this means that a batch request to
Tyk for three resources with the same API key will have three requests applied to their session quota and request limiting could become active if they are being throttled.

Tyk reconstructs the API request based on the data in the batch request, this is to ensure that Tyk is not being used to proxy requests to other hosts outside of the upstream
API being accessed.

Batch requests are created by POSTing to the /{api-id}/tyk/batch endpoint, these requests do not require a valid key, but their request list does,
here is a sample request body:

{
    "requests": [
        {
            "method": "GET",
            "headers": {
                "x-tyk-test": "1",
                "x-tyk-version": "1.2",
                "authorization": "1dbc83b9c431649d7698faa9797e2900f"
            },
            "body": "",
            "relative_url": "get"
        },
        {
            "method": "GET",
            "headers": {
                "x-tyk-test": "2",
                "x-tyk-version": "1.2",
                "authorization": "1dbc83b9c431649d7698faa9797e2900f"
            },
            "body": "",
            "relative_url": "get"
        }
    ],
    "suppress_parallel_execution": false
}

the response will will be a structured reply that encapsulates the responses for each of the outbound requests. If suppress_parallel_execution is set to true,
requests will be made synchronously, if set to false then they will run in parallel and the response order is not guaranteed.

A response to the above when pointing at the httpbin(1) would look like:

[
    {
        "relative_url": "get",
        "code": 200,
        "headers": {
            "Access-Control-Allow-Credentials": [
                "true"
            ],
            "Access-Control-Allow-Origin": [
                "*"
            ],
            "Content-Length": [
                "497"
            ],
            "Content-Type": [
                "application/json"
            ],
            "Date": [
                "Wed, 12 Nov 2014 15:32:43 GMT"
            ],
            "Server": [
                "gunicorn/18.0"
            ],
            "Via": [
                "1.1 vegur"
            ]
        },
        "body": "{
  "args": {}, 
  "headers": {
    "Accept-Encoding": "gzip", 
    "Authorization": "1dbc83b9c431649d7698faa9797e2900f", 
    "Connect-Time": "2", 
    "Connection": "close", 
    "Host": "httpbin.org", 
    "Total-Route-Time": "0", 
    "User-Agent": "Go 1.1 package http", 
    "Via": "1.1 vegur", 
    "X-Request-Id": "6a22499a-2776-4aa1-80c0-686581a8be4d", 
    "X-Tyk-Test": "2", 
    "X-Tyk-Version": "1.2"
  }, 
  "origin": "127.0.0.1, 62.232.114.250", 
  "url": "http://httpbin.org/get"
}"
    },
    {
        "relative_url": "get",
        "code": 200,
        "headers": {
            "Access-Control-Allow-Credentials": [
                "true"
            ],
            "Access-Control-Allow-Origin": [
                "*"
            ],
            "Content-Length": [
                "497"
            ],
            "Content-Type": [
                "application/json"
            ],
            "Date": [
                "Wed, 12 Nov 2014 15:32:43 GMT"
            ],
            "Server": [
                "gunicorn/18.0"
            ],
            "Via": [
                "1.1 vegur"
            ]
        },
        "body": "{
  "args": {}, 
  "headers": {
    "Accept-Encoding": "gzip", 
    "Authorization": "1dbc83b9c431649d7698faa9797e2900f", 
    "Connect-Time": "7", 
    "Connection": "close", 
    "Host": "httpbin.org", 
    "Total-Route-Time": "0", 
    "User-Agent": "Go 1.1 package http", 
    "Via": "1.1 vegur", 
    "X-Request-Id": "1ab61f50-51ff-4828-a7e2-17240385a6d2", 
    "X-Tyk-Test": "1", 
    "X-Tyk-Version": "1.2"
  }, 
  "origin": "127.0.0.1, 62.232.114.250", 
  "url": "http://httpbin.org/get"
}"
    }
]

With the body for each request string encoded in the body field.

expire_analytics_after

If you are running a busy API, you may want to ensure that your MongoDB database does not overflow with old data. Set the expire_analytics_after value to the number of seconds you would like the data to last for. Setting this flag to anything above 0 will set an expireAt field for each record that is written to the database.

Important: Tyk will not create the expiry index for you, in order to implement data expiry for your analytics data, ensure that the index is created, this is very easily achieved using the mongoDB command line interface as described here.

dont_set_quota_on_create (default false)

If this is set to true, when the API is used to edit, create or add keys, the quota cache in Redis will not be re-set. By default, all updates or creates to Keys that have Quotas set will re-set the quota (This has been the default behaviour since 1.0).

This behaviour can be bypassed on a case-by-case basis by using the suppress_reset parameter when making a REST API request, this is the advised mode of operation as it allows for manual, granular control over key quotas and reset timings.

cache_options

This section enables you to configure the caching behaviour of Tyk and to enable or disable the caching middleware for your API.

cache_options.enable_cache

Set this value to true i the cache should be enabled for this endpoint, setting it to false will stop all caching behaviour.

cache_options.cache_timeout

The amount of time, in seconds, to keep cached objects, defaults to 60 seconds.

cache_options.cache_all_safe_requests

Set this to true if you want all safe requests (GET, HEAD, OPTIONS) to be cached, this is a blanket setting for APIs where caching is required but you don’t want to set individual paths up
in the definition.

cache_options.enable_upstream_cache_control

Set this to true if you want your application to control the cache options for Tyk (TTL and Whether to cache or not). See the caching section for implementation details.

response_processors

Response processors need to be specifically defined so they are loaded on API creation, otherwise the middleware will not fire. In order to have the two main response middleware components fire, the following configuration object should be supplied:

"response_processors": [
    {
      "name": "header_injector",
      "options": {
        "add_headers": {"name": "value"},
        "remove_headers": ["name"]
      }
    },
    {
      "name": "response_body_transform",
      "options": {}
    }
]

The options for the header_injector are global, and will apply to all outbound requests.

CORS

It is possible to enable CORS for certain APIs so users can make browser-based requests. The Cors section is added to an API definition as follows:

 ```
 "CORS": {
    "enable": true,
    "allowed_origins": [
      "http://foo.com"
    ]
 },
 ```

The CORS middleware has many options, these include:

CORS.allowed_origins

A list of origin domains to allow access from

CORS.allowed_methods

A list of methods to allow access via

CORS.allowed_headers

Headers that are allowed within a request

CORS.exposed_headers

Headers that are exposed back in the response

CORS.allow_credentials

Whether credentials (cookies) should be allowed

CORS.max_age

Maximum age of credentials

CORS.options_pasthrough

Whether OPTIONS requests should pass through to the rest of the middleware. Update in v1.9: If this option is selected, OPTIONS requests will be completely ignored by the Tyk middleware, this means that pre-flight requests generated by web-clients such as SwaggerUI or the Tyk Portal documentation system will be able to test the API using trial keys

enable_jwt

Set JWT as the access method for this API

jwt_signing_method

Either HMAC or RSA – HMAC requires a shared secret while RSA requires a public key to use to verify against. Please see the seciton on JSON web tokens for more detail on how to generate these

uptime_tests

This section defines the uptime tests to run for this API

uptime_tests.check_list

A list of tests to run, takes the form:

```
uptime_tests: {
    check_list: [
      {
        "url": "http://google.com/"
      },
      {
        "url": "http://posttestserver.com/post.php?dir=uptime-checker",
        "method": "POST",
        "headers": {
          "this": "that",
          "more": "beans"
        },
        "body": "VEhJUyBJUyBBIEJPRFkgT0JKRUNUIFRFWFQNCg0KTW9yZSBzdHVmZiBoZXJl"
      }
    ]
},
```

Please see the section on uptime tests for a full write-up on how uptime tests work and how to configure them

domain

The domain to bind this API to – domains can have multiple listen paths, so multiple APIs can be spanned across a domain using different listen_paths, must be a valid domain name, without the protocol section (e.g. http or https)

do_not_track

Set this value to true to have traffic for this API completely ignored