Working with API Templates using the Dashboard API

Last updated: Mar 28, 2024 9 minutes read.

API Templates are an API governance feature provided to streamline the process of creating Tyk OAS APIs. An API template is an asset managed by Tyk Dashboard that is used as the starting point - a blueprint - from which you can create a new Tyk OAS API definition.

The Tyk Dashboard API provides the following functionality to support working with API templates:

Note

API Templates are exclusive to Tyk OAS APIs.

Structure of an API template

An API template asset has the following structure:

id: a unique string type identifier for the template
kind: the asset type, which is set to oas-template
name: human-readable name for the template
description: a short description of the template, that could be used for example to indicate the configuration held within the template
data: a Tyk OAS API definition, the content of which will be used for templating APIs
_id: a unique identifier assigned by Tyk when the template is registered in the Dashboard database

Registering a template with Tyk Dashboard

To register an API template with Tyk, you pass the asset in the body of a POST request to the dashboard’s /api/assets endpoint.

For example, if you send this command to the endpoint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


curl --location 'http://localhost:3000/api/assets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d9957aff302b4f5e5596c86a685e63d8' \
--data '{
  "kind": "oas-template",
  "name": "my-template",
  "description": "My first template",
  "id": "my-unique-template-id",
  "data": {
    "info": {
      "title": "",
      "version": ""
    },
    "openapi": "3.0.3",
    "paths": {
      "/anything": {
        "post": {
          "operationId": "anythingpost",
          "responses": {
            "200": {
              "description": ""
            }
          }
        }
      }
    },
    "x-tyk-api-gateway": {
      "middleware": {
        "global": {
          "cache": {
            "enabled": true,
            "timeout": 5,
            "cacheAllSafeRequests": true
          }
        },
        "operations": {
          "anythingpost": {
            "requestSizeLimit": {
              "enabled": true,
              "value": 100
            }
          }
        }
      }
    }
  }
}'

Tyk will respond with HTTP 201 Created and will provide this payload in response:

{
    "Status": "success",
    "Message": "asset created",
    "Meta": "65e8c352cb71918520ff660c",
    "ID": "my-unique-template-id"
}

Here Meta contains the database ID (where the asset has been registered in the persistent storage) and ID contains the unique identifier for the template. This unique identifier will be automatically generated by Tyk if none was provided in the id of the template asset provided in the curl request.

Applying a template when creating an API from an OpenAPI document

When creating an API on Tyk using an OpenAPI document describing your upstream service, you can use the /apis/oas/import endpoint to import the OpenAPI description and apply it to your API.

If you have a template registered with your Dashboard, you can use this as the starting point for your new API. Tyk will combine the OpenAPI document with the template, automating the configuration of any element in the Tyk OAS API definition as defined in your chosen template.

You’ll need to identify the template to be used during the import. You can use either its unique id or the database ID that was assigned when the template was registered with Tyk Dashboard. You provide either the id or _id in the templateID query parameter in the call to /oapis/oas/import.

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


curl --location 'http://localhost:3000/api/apis/oas/import?templateID=my-unique-template-id' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <DASHBOARD_SECRET>' \
--data '{
  "components": {},
  "info": {
    "title": "my-open-api-document",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "http://httpbin.org"
    }
  ],
  "paths": {
    "/xml": {
      "get": {
        "operationId": "xmlget",
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  }
}'

Tyk will respond with HTTP 200 OK and will provide this payload in response:

{
    "Status": "OK",
    "Message": "API created",
    "Meta": "65e8c4f4cb71918520ff660d",
    "ID": "970560005b564c4755f1db51ca5660e6"
}

Here Meta contains the database ID (where the API has been registered in the persistent storage) and ID contains the unique identifier for the API. This unique identifier will be automatically generated by Tyk as none was provided in the id field of the x-tyk-api-gateway.info field provided in the curl request.

The new Tyk OAS API will have this definition, combining the OpenAPI description provided in the body of the curl request with the template with Id my-unique-template-id:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81


{
  "info": {
    "title": "my-open-api-document",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "http://localhost:8181/"
    },
    {
      "url": "http://httpbin.org"
    }
  ],
  "security": [],
  "paths": {
    "/anything": {
      "post": {
        "operationId": "anythingpost",
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    },
    "/xml": {
      "get": {
        "operationId": "xmlget",
        "responses": {
          "200": {
            "description": ""
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {}
  },
  "x-tyk-api-gateway": {
    "info": {
      "dbId": "65e8c4f4cb71918520ff660d",
      "id": "970560005b564c4755f1db51ca5660e6",
      "orgId": "65d635966ec69461e0e7ee52",
      "name": "my-open-api-document",
      "state": {
        "active": true,
        "internal": false
      }
    },
    "middleware": {
      "global": {
        "cache": {
          "cacheResponseCodes": [],
          "cacheByHeaders": [],
          "timeout": 5,
          "cacheAllSafeRequests": true,
          "enabled": true
        }
      },
      "operations": {
        "anythingpost": {
          "requestSizeLimit": {
            "enabled": true,
            "value": 100
          }
        }
      }
    },
    "server": {
      "listenPath": {
        "strip": true,
        "value": "/"
      }
    },
    "upstream": {
      "url": "http://httpbin.org"
    }
  }
}

Note that the GET /xml endpoint from the OpenAPI description and the POST /anything endpoint from the template (complete with requestSizeLimit middleware) have both been defined in the API definition. API-level caching has been enabled, as configured in the template. Tyk has included the server entry from the OpenAPI description (which points to the upstream server) and added the API URL on Tyk Gateway (as explained here).

Applying a template when creating an API from a Tyk OAS API definition

When creating an API using a complete Tyk OAS API definition (which includes x-tyk-api-gateway), you can use the /apis/oas endpoint to import the API defintiion.

If you have a template registered with your Dashboard, you can use this as the starting point for your new API. Tyk will combine the API definition with the template, automating the configuration of any element defined in your chosen template.