Skip to main content
An API Template is a starting point for a new Tyk OAS API. It is an Asset that Tyk Dashboard stores, and it contains some of the configuration of a Tyk OAS API definition. When you create an API from a Template, Tyk Dashboard copies the configuration in the Template into the new API. The default Template is a blank API definition. Your custom Templates contain some configuration, for example cache configuration, or default endpoints with pre-configured middleware. When you create a new API from a custom Template, the elements of the API configuration in the Template are pre-configured for you.
API Templates are exclusive to Tyk OAS APIs. You can manage them with the Tyk Dashboard API or in Tyk Dashboard.

​
When to Use API Templates

​
Gateway Agnostic API Design

When you work with upstream services that have OpenAPI descriptions, your service developers don’t need to learn about Tyk. You can create and maintain a set of Templates that contain the Tyk-specific configuration (x-tyk-api-gateway) that your published APIs need. To create an API on Tyk, you import the OpenAPI document and select the correct Template. Tyk combines the OpenAPI description with the Template to produce a valid Tyk OAS API.

​
Standardizing API Configuration

Your external facing APIs can have specific requirements, for example authentication, caching or a health check endpoint. You can define API Templates that configure these fields correctly when you create APIs on Tyk.

​
How API Templates Work

An API Template is a blueprint from which you build new APIs. It is an incomplete JSON representation of a Tyk OAS API definition. You use it as the starting point when you create a new API on Tyk. A Template can pre-configure as much or as little of the API definition as you need. The blank API definition that you start from when you don’t choose a Template is itself a Template. Tyk Dashboard applies Templates only when you create an API. You can’t apply a Template to an existing API. Before you can use a Template as the basis for an API, you must register the Template with Tyk Dashboard.

​
Structure of an API Template

An API template asset has the following structure:

​
Applying a Template

When you use a Template to create an API, the fields configured in data are pre-set in your new API. You can change them while you create the API and afterwards. Tyk doesn’t create a link between the API and the Template. Changes that you make to the API don’t affect the Template, and changes to the Template don’t affect the API.
Categories are not part of API Templates. You can’t pre-configure them in a Template. Set the Categories when you create the API, or edit them afterwards.

​
Merging with an OpenAPI Description or Tyk OAS API Definition

When you use a Template to create an API by importing an OpenAPI document or a full Tyk OAS API definition, Tyk combines the Template with the imported document. If the Template contains the x-tyk-api-gateway extension, Tyk applies it to the new API. Where the OpenAPI description and the Template configure the same field:
  • For maps, such as paths and components, Tyk adds new keys alongside the keys from the Template. If a key in the OpenAPI description matches one in the Template, the OpenAPI description takes precedence.
  • For arrays, such as servers and tags, the values in the OpenAPI description replace the values in the Template.

​
Fragments in API Templates

From TYk 5.16.0, a Template can contain Fragment references in place of static configuration. When you create an API from the Template, Tyk Dashboard copies the references into the new API. The new API therefore stays linked to the Fragments, and receives any later changes to them. This lets you combine the two. The Template sets up a new API. The Fragments in it keep shared configuration, such as security settings, the same across every API that you create from the Template. Tyk Dashboard validates a Template with its Fragments resolved when you save the Template, and when you change a Fragment that the Template references. You can’t delete a Fragment while a Template references it. When you create a Template from an existing API, the Template keeps the Fragment references of the API.

​
Use API Templates in Tyk Dashboard

API Templates are in the Assets section of the Tyk Dashboard menu, under API Templates. To see them, you need the api_assets permission. This screen lists all the Templates registered with Tyk, with their names, Template IDs and descriptions. You can create and manage Templates from this screen. API Templates

​
Create a Template

  1. Go to Assets > API Templates and click Add Template.
  2. On the Create API Template screen, in Template info, enter a Template Name and a Template Description. Both are required. The Template doesn’t need to be a complete or valid API definition.
  3. Configure the API-level settings on the Settings tab, and the endpoint-level settings on the Endpoints tab. Configure the Template
  4. Click Save Template.
The API Templates screen now lists your new Template, with its unique Template ID. You can use this ID to access the Template with the Tyk Dashboard API.

​
Create a Template from an API

You can use an existing API deployed on Tyk as the basis for a new API Template. This is a good way to build up a portfolio of standardized APIs once you’ve configured your first API correctly.
  1. Open the API that you want to use as your starting point.
  2. Click Actions and select Create API template. Create a new Template from an existing API
  3. On the Create API Template screen, enter a Template Name and a Template Description.
  4. Change any of the API-level and endpoint-level settings that you need.
  5. Click Save Template.
If the API uses Fragments, the Template keeps the Fragment references.

​
Create an API from a Template

You can base a new API on a Template in two ways:
  • Go to Assets > API Templates. For the Template that you want to use, open the Actions menu and select Create API from Template. Select Create API from Template
  • Go to the APIs list and click Add New API. In the API Style step, select an HTTP API with Tyk OAS, then select the Template in the API Templates step. Tyk Dashboard shows this step only when at least one Template exists. Select the Template you want to use
Both ways take you to the API Designer, where the settings from your Template are pre-configured. To create an API from a Template, you need write access to APIs.

​
Import an API with a Template

On the Import API screen, select the OpenAPI type to create an API from an OpenAPI description or Tyk OAS API definition. Provide the document to Tyk Dashboard in one of these ways:
  • Paste API Definition: paste the JSON into the text editor
  • Import from File: upload a file that contains the JSON
  • Pull from URL: provide a URL to the JSON
Then select the Template that you want to use in the Template name field, above Manual configuration options: Select the Template you want to use

​
Edit a Template

  1. Go to Assets > API Templates.
  2. Click the name of the Template, or open its Actions menu and select Edit Template. If you have only read access to Templates, the menu item is View Template.
  3. On the API Template Details screen, click Edit, and change the settings. To view and change the raw JSON of the Template, open the Actions menu and select View Raw Template. To return to the form, select View Template Designer.
  4. Click Save Template.

​
Delete a Template

  1. Go to Assets > API Templates and open the Template.
  2. On the API Template Details screen, open the Actions menu and select Delete Template.
  3. Confirm the deletion.
You can’t undo the deletion. Tyk Dashboard removes the Template from its database, and you can’t recover it.

​
Use API Templates with the Tyk Dashboard API

API Templates are Assets with the kind set to oas-template. To register a Template, send it to POST /api/assets. The data field holds the Template, in the same format as a Tyk OAS API definition. If you omit id, Tyk Dashboard generates one. To apply a Template when you create an API, add the templateID query parameter to POST /api/apis/oas/import or POST /api/apis/oas. Its value is the id or the database ID (_id) of the Template. Tyk Dashboard combines the document in the request with the Template, using the rules in Merging with an OpenAPI Description or Tyk OAS API Definition.

​
Use API Templates with Tyk Sync

Tyk Sync 1.5 and later can dump, publish and sync API Templates together with your APIs and Policies.