Working with Tyk OAS APIs

Armed with a Tyk OAS API definition, in YAML or JSON format, you can use this to create an API in Tyk Dashboard with only a few clicks.

1. Start by selecting APIs from the API Management section

   

2. Now select Add New API and then, choose Import.

   

   Note that you can optionally apply an API template by choosing Start from template as explained here, however in this explanation we will not be applying a template.

3. From the Import API screen, select Tyk API because the object you want to import to Tyk is a complete API definition.

   

   Note

   On the Import API screen, there are three options for Import Type, it is important to select the correct one for the object that you want to load into Tyk:

   • openAPI is used only for OpenAPI descriptions (without the Tyk Vendor Extension)
   • TykAPI is used for a full Tyk OAS API definition (comprising OpenAPI description plus Tyk Vendor Extension) or Tyk Classic API definition
   • WSDL/XML is used for WSDL/XML content and will result in a Tyk Classic API

4. Now you can paste the entire Tyk OAS API definition into the text editor.

   

5. Select Import API to complete the import and create the API based on your API definition.

When making calls to the Tyk Dashboard API you’ll need to set the domain name and port for your environment and provide credentials in the Authorization field for Tyk to authorize your request, as follows:

You can obtain your authorization credential (Dashboard API key) from the Tyk Dashboard UI:

• Select Edit profile from the dropdown that appears when you click on your username in the top right corner of the screen
• Scroll to the bottom of the page were you will see your Tyk Dashboard API Access Credentials

You will also need to have ‘admin’ or ‘api:write’ permission if RBAC is enabled.

To create the API in Tyk, you simply send your Tyk OAS API Definition in the payload to the POST /api/apis/oas endpoint of your Tyk Dashboard API.

Using this API definition it is possible to create a Tyk OAS API on your Tyk Gateway that forwards requests to the Swagger Petstore request/response service.

curl -H "Authorization: ${DASH_KEY}" -H "Content-Type: application/json" ${DASH_URL}/apis/oas -d "$(wget -qO- https://bit.ly/39jUnuq)"

Check request response

If the command succeeds, you will see the following response, where Meta contains the unique identifier (id) for the API you have just created. If you did not provide a value in the id field, then Tyk will automatically assign one.

{
    "Status": "OK",
    "Message": "API created",
    "Meta": {NEW-API-ID}
}

What you have done is to send a Tyk OAS API definition to Tyk Dashboard’s /api/apis/oas endpoint resulting in the creation of the API in your Tyk Dashboard which will automatically deploy it to your Gateway.

You can use the optional templateId parameter to apply an API Template to your API definition when creating the API.

When making calls to the Tyk Gateway API you’ll need to set the domain name and port for your environment and provide credentials in the x-tyk-authorization field for Tyk to authorize your request, as follows:

To create the API in Tyk, you simply send your Tyk OAS API Definition in the payload to the POST /tyk/apis/oas endpoint of your Tyk Gateway API.

Using this minimal API definition it is possible to create a Tyk OAS API on your Tyk Gateway using only 30 lines:

curl --location --request POST 'http://{your-tyk-host}:{port}/tyk/apis/oas' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw 
'{
  "info": {
    "title": "Petstore",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "components": {},
  "paths": {},
  "x-tyk-api-gateway": {
    "info": {
      "name": "Petstore",
      "state": {
        "active": true
      }
    },
    "upstream": {
      "url": "https://petstore.swagger.io/v2"
    },
    "server": {
      "listenPath": {
        "value": "/petstore/",
        "strip": true
      }
    }
  }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the unique identifier (id) for the API you have just created. If you did not provide a value in the id field, then Tyk will automatically assign one.

{
    "key": {NEW-API-ID},
    "status": "ok",
    "action": "added"
}

What you have done is to send a Tyk OAS API definition to Tyk Gateway’s /tyk/apis/oas endpoint resulting in the creation of the API in your Tyk Gateway.

Restart or hot reload

Once you have created your API you need to load it into the Gateway so that it can serve traffic. To do this you can either restart the Tyk Gateway or issue a hot reload command:

curl -H "x-tyk-authorization: {your-secret}" -s http://{your-tyk-host}:{port}/tyk/reload/group

You can go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) to see where Tyk has stored your Tyk OAS API Definition.

If you have a valid OAS 3.0 compliant OpenAPI description, in YAML or JSON format, you can use this to create an API in Tyk Dashboard with only a few clicks.

1. Start by selecting APIs from the API Management section

   

2. Now select Add New API and then, choose Import.

   

3. From the Import API screen, select openAPI because the object you want to import to Tyk is an OpenAPI description.

   

   Note

   On the Import API screen, there are three options for Import Type, it is important to select the correct one for the object that you want to load into Tyk:

   • openAPI is used only for OpenAPI descriptions (without the Tyk Vendor Extension)
   • TykAPI is used for a full Tyk OAS API definition (comprising OpenAPI description plus Tyk Vendor Extension) or Tyk Classic API definition
   • WSDL/XML is used for WSDL/XML content and will result in a Tyk Classic API

4. Now you can choose the location of the OpenAPI description, which can be:

   • pasted into the text editor
   • uploaded using a file picker
   • retrieved from a file server

   

5. You can optionally apply an API template from the drop-down.

   

6. You can configure the listen path and upstream (target) URL in the Manual configuration options section. Note that if you do not provide a listen path, Tyk will default to / and if you do not provide an upstream URL, Tyk will use the first value provided in the servers.url section in the OpenAPI description.

   

7. Tyk can automatically configure the request processing middleware chain based upon configuration defined by the OpenAPI Specification. If your OpenAPI desription contains the relevant data then select the characteristics you would like to configure.

   

   Middleware	OpenAPI data used for configuration
   Request validation	Endpoints that have requestBody or schema
   Mock response	Endpoints with examples or schema
   Client authentication	Defined in security and securitySchemes
   Allow list	Restrict access only to declared endpoint paths

8. Select Import API to complete the import and create the API based on your API definition.

When making calls to the Tyk Dashboard API you’ll need to set the domain name and port for your environment and provide credentials in the Authorization field for Tyk to authorize your request, as follows:

You can obtain your authorization credential (Dashboard API key) from the Tyk Dashboard UI:

• Select Edit profile from the dropdown that appears when you click on your username in the top right corner of the screen
• Scroll to the bottom of the page were you will see your Tyk Dashboard API Access Credentials

You will also need to have ‘admin’ or ‘api:write’ permission if RBAC is enabled.

To create the API in Tyk, you simply send your OpenAPI document in the payload to the POST /api/apis/oas/import endpoint of your Tyk Dashboard API.

The optional parameters are:

Check request response

If the command succeeds, you will see the following response, where Meta contains the unique identifier (id) for the API you have just created.

{
    "Status": "OK",
    "Message": "API created",
    "Meta": {NEW-API-ID}
}

When making calls to the Tyk Gateway API you’ll need to set the domain name and port for your environment and provide credentials in the x-tyk-authorization field for Tyk to authorize your request, as follows:

To create the API in Tyk, you simply send your OpenAPI document in the payload to the POST /tyk/apis/oas/import endpoint of your Tyk Gateway API.

The optional parameters are:

Check request response

If the command succeeds, you will see the following response, where key contains the unique identifier (id) for the API you have just created.

{
    "key": {NEW-API-ID},
    "status": "ok",
    "action": "added"
}

Restart or hot reload

Once you have created your API you need to load it into the Gateway so that it can serve traffic. To do this you can either restart the Tyk Gateway or issue a hot reload command:

curl -H "x-tyk-authorization: {your-secret}" -s http://{your-tyk-host}:{port}/tyk/reload/group

You can go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) to see where Tyk has stored your Tyk OAS API Definition.

If you have an updated OpenAPI description or Tyk OAS API definition, in YAML or JSON format, you can use this to modify your existing API in Tyk Dashboard with only a few clicks.

1. Start by selecting your API from the list on the APIs page in the API Management section.

2. Now select Update OAS from the Actions dropdown.

   

3. Now you can choose the location of the file that you want to use to update your API, which can be:

   • pasted into the text editor
   • uploaded using a file picker
   • retrieved from a file server

   

4. You can re-configure the listen path and upstream (target) URL in the Manual configuration options section, but if you do not provide these then Tyk will leave them unchanged.

5. Tyk must select the options to automatically configure the request processing middleware chain based upon configuration defined by the OpenAPI Specification for any new endpoints added in the update. If your OpenAPI desription contains the relevant data then select the characteristics you would like to configure.

   

   Middleware	OpenAPI data used for configuration
   Request validation	Endpoints that have requestBody or schema
   Mock response	Endpoints with examples or schema
   Client authentication	Defined in security and securitySchemes
   Allow list	Restrict access only to declared endpoint paths

6. Select Import API to complete the update.

When making calls to the Tyk Dashboard API you’ll need to set the domain name and port for your environment and provide credentials in the Authorization field for Tyk to authorize your request, as follows:

You can obtain your authorization credential (Dashboard API key) from the Tyk Dashboard UI:

• Select Edit profile from the dropdown that appears when you click on your username in the top right corner of the screen
• Scroll to the bottom of the page were you will see your Tyk Dashboard API Access Credentials

You will also need to have ‘admin’ or ‘api:write’ permission if RBAC is enabled.

Applying an Updated OpenAPI Description

To update just the OpenAPI description of your API in Tyk, you simply send the OpenAPI document in the payload to the PATCH /api/apis/oas/{API-ID} endpoint of your Tyk Gateway API.

You need to specify which API to update - and so so using the API-ID value from the response you received from Tyk when creating the API. You can find this in the x-tyk-api-gateway.info.id field of the Tyk OAS API Definition stored in your main storage.

Applying an Updated Tyk OAS API Definition

To update the whole API in Tyk, you simply send the Tyk OAS API definition in the payload to the PATCH /api/apis/oas/{API-ID} endpoint of your Tyk Gateway API.

You need to specify which API to update - and so so using the API-ID value from the response you received from Tyk when creating the API. You can find this in the x-tyk-api-gateway.info.id field of the Tyk OAS API Definition stored in your main storage.

Check request response

If the command succeeds, you will see the following response, where Meta contains the unique identifier (id) for the API you have just updated:

{
    "Status": "OK",
    "Message": "API modified",
    "Meta": {API-ID}
}

When making calls to the Tyk Gateway API you’ll need to set the domain name and port for your environment and provide credentials in the x-tyk-authorization field for Tyk to authorize your request, as follows:

Applying an Updated OpenAPI Description

To update just the OpenAPI description of your API in Tyk, you simply send the OpenAPI document in the payload to the PATCH /tyk/apis/oas/{API-ID} endpoint of your Tyk Gateway API.

You need to specify which API to update - and so so using the API-ID value from the response you received from Tyk when creating the API. You can find this in the x-tyk-api-gateway.info.id field of the Tyk OAS API Definition that Tyk has stored in the /apps folder of your Tyk Gateway installation.

Applying an Updated Tyk OAS API Definition

To update the whole API in Tyk, you simply send the Tyk OAS API definition in the payload to the PATCH /tyk/apis/oas/{API-ID} endpoint of your Tyk Gateway API.

You need to specify which API to update - and so so using the API-ID value from the response you received from Tyk when creating the API. You can find this in the x-tyk-api-gateway.info.id field of the Tyk OAS API Definition that Tyk has stored in the /apps folder of your Tyk Gateway installation.

Check request response

If the command succeeds, you will see the following response, where key contains the unique identifier (id) for the API you have just updated:

{
    "key": {API-ID},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload

Once you have updated your API you need to load it into the Gateway so that it can serve traffic. To do this you can either restart the Tyk Gateway or issue a hot reload command:

curl -H "x-tyk-authorization: {your-secret}" -s http://{your-tyk-host}:{port}/tyk/reload/group

1. Start by selecting your API from the list on the APIs page in the API Management section.

2. Select Export API from the Actions dropdown.

   

3. Now you can choose what you want to export, the filename (a default is offered which is based on the API Id) and the file format (JSON or YAML).

   

4. Finally select Export to save the file to your local machine.

When making calls to the Tyk Dashboard API you’ll need to set the domain name and port for your environment and provide credentials in the Authorization field for Tyk to authorize your request, as follows:

You can obtain your authorization credential (Dashboard API key) from the Tyk Dashboard UI:

• Select Edit profile from the dropdown that appears when you click on your username in the top right corner of the screen
• Scroll to the bottom of the page were you will see your Tyk Dashboard API Access Credentials

You will also need to have ‘admin’ or ‘api:write’ permission if RBAC is enabled.

To export an API asset, you use the GET /api/apis/oas/{API-ID}/export endpoint, indicating whether you require the full Tyk OAS API definition or only the OpenAPI description using the mode parameter.

Where:

• API-ID is the unique id assigned in the Tyk Vendor Extension that identifies the API
• mode to identify the asset to export: public for the OpenAPI description (default empty for full API definition)
• Content-Type to select the format for the exported asset: application/x-yaml or application/json

When making calls to the Tyk Gateway API you’ll need to set the domain name and port for your environment and provide credentials in the x-tyk-authorization field for Tyk to authorize your request, as follows:

To export an API asset, you use the GET /tyk/apis/oas/{API-ID}/export endpoint, indicating whether you require the full Tyk OAS API definition or only the OpenAPI description using the mode parameter.

Where:

• API-ID is the unique id assigned in the Tyk Vendor Extension that identifies the API
• mode=public to export the OpenAPI description (otherwise, export the full API definition)