Update existing Tyk API with changes in your OpenAPI definition

Last updated: 10 minutes read.

Introduction

As developers working on API development, it is necessary for us to constantly update the OpenAPI definition. This definition is normally generated either from our codebase or created using API design tools (such as Swagger Editor, Postman and Stoplight)

Note

In order to use the Gateway API you will need an API key for your Gateway and one command to create the API and make it live.

Open Source

Tutorial: Update Tyk OAS API definition with an updated OpenAPI definition

Make sure you know your Tyk API secret

Your Tyk Gateway API secret is stored in your tyk.conf file, the property is called secret. You will need to use this as a header called x-tyk-authorization to make calls to the Gateway API.

Create an API

For the sake of this tutorial, create a new API by sending this Tyk OAS API Definition https://bit.ly/39tnXgO to the Gateway API endpoint (this is an example that contains the very minimal required fields):

Property Description
Resource URL /tyk/apis/oas
Method POST
Type None
Body Tyk OAS API Definition
Parameters None

Note

For the Tyk Gateway, the default{port} is 8080.

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-oas/",
        "strip": true
      }
    }
  }
}'

Check request response

If the command succeeds, you will see the following response, where the key value contains the newly created api-id:

{
    "key": {api-id},
    "status": "ok",
    "action": "added"
}

Restart or hot reload

Once you have created your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Update your OpenAPI definition

Now let’s assume you made a change in your OpenAPI definition (as mentioned above, from code or a tool, outside Tyk’s domain). The change could be adding a new path, changing a description or anything that changes the definition of the API.

In this example we added a new endpoint, POST /pet, with a schema that validates the payload it receives (requestBody.content.application/json.schema) and a new security scheme (the OpenAPI definition is in the code snippet in the next section, just to avoid repetition)

Update the Tyk API definition using just your updated OpenAPI definition

You can update your Tyk OAS API definition very simply - by providing your OpenAPI definition as an OpenAPI document with the PATCH request. Tyk will use the content of the OpenAPI document to update just the OpenAPI section in the Tyk OAS API definition.

Property Description
Resource URL /tyk/apis/oas/{api-id}
Method PATCH
Type None
Body OAS API Definition
Parameters Path: {api-id}
curl --location --request PATCH 'http://{your-tyk-host}:{port}/tyk/apis/oas/{api-id}' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw '{
   "info":{
      "title":"Petstore",
      "version":"1.0.0"
   },
   "openapi":"3.0.3",
   "basic-config-and-security/security":[
      {
         "api_key":[
            
         ]
      }
   ],
   "components":{
      "securitySchemes":{
         "api_key":{
            "type":"apiKey",
            "name":"api_key",
            "in":"header"
         }
      },
      "schemas":{
         "Pet":{
            "required":[
               "name"
            ],
            "type":"object",
            "properties":{
               "id":{
                  "type":"integer",
                  "format":"int64",
                  "example":10
               },
               "name":{
                  "type":"string",
                  "example":"doggie"
               },
               "category":{
                  "type":"string",
                  "example":"dog"
               },
               "status":{
                  "type":"string",
                  "description":"pet status in the store",
                  "enum":[
                     "available",
                     "pending",
                     "sold"
                  ]
               }
            }
         }
      }
   },
   "paths":{
      "/pet":{
         "post":{
            "operationId":"addPet",
            "requestBody":{
               "description":"Update an existent pet in the store",
               "content":{
                  "application/json":{
                     "schema":{
                        "$ref":"#/components/schemas/Pet"
                     }
                  }
               },
               "required":true
            },
            "responses":{
               "405":{
                  "description":"Invalid input"
               }
            },
            "summary":"Add a new pet to the store",
            "tags":[
               "pet"
            ]
         }
      }
   }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the newly created API ID:

{
    "key": {api-id},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload your Gateway

Once you have created your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Protect your API based on the OpenAPI definition

Previously you updated the Tyk OAS API definition with a new OpenAPI definition, that describes a new security mechanism. In order for Tyk Gateway to start protecting the API using this authentication mechanism, it needs to be enabled within the Tyk section of the Tyk OAS API definition.

To do this you would add the query parameter authentication=true to the PATCH request you just performed; this tells Tyk to automatically enable authentication, based on the settings in the OpenAPI definition.

Property Description
Resource URL /tyk/apis/oas/{api-id}
Method PATCH
Type None
Body OAS API Definition
Parameters Path: {api-id} Query: authentication
curl --location --request PATCH 'http://{your-tyk-host}:{port}/tyk/apis/oas/{API_ID}?authentication=true' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "info": {
        "title": "Petstore",
        "version": "1.0.0"
    },
    "openapi": "3.0.3",
    "basic-config-and-security/security": [
      {
        "api_key": []
      }
    ],
    "components": {
      "securitySchemes": {
        "api_key": {
          "type": "apiKey",
          "name": "api_key",
          "in": "header"
        }
      }
    },
    "paths": {
        "/pet": {
            "post": {
                "operationId": "addPet",
                "requestBody": {
                    "$ref": "#/components/requestBodies/Pet"
                },
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    }
                },
                "summary": "Add a new pet to the store",
                "tags": [
                    "pet"
                ]
            }
        }
    }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the newly created API ID:

{
    "key": {api-id},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload your Gateway

Once you have updated your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Check your OAS API definition

Go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) and check the newly modified Tyk OAS API Definition. You’ll notice that the following configuration has been added under the x-tyk-api-gateway section, which now tells your Tyk Gateway to protect your API using an Authentication token.

{
  ...
  "x-tyk-api-gateway": {
    ...
    "server": {
      ...
      "authentication": {
        "enabled": true,
        "securitySchemes": {
          "api_key": {
            "enabled": true,
            "header": {
              "enabled": true
            }
          }
        }
      }
    }
  }
}

Explicitly allow access to documented endpoints

Tyk Gateway’s allow list function explicitly allows access just to paths that are documented in the Tyk OAS API definition. You can enable this when updating a Tyk API OAS definition using the PATCH method by passing the allowList query parameter with the payload.

Property Description
Resource URL /tyk/apis/oas/{api-id}
Method PATCH
Type None
Body OAS API Definition
Parameters Path: {api-id} Query: allowList
curl --location --request PATCH 'http://{your-tyk-host}:{port}/tyk/apis/oas/{api-id}?allowList=true' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "info": {
        "title": "Petstore",
        "version": "1.0.0"
    },
    "openapi": "3.0.3",
    "basic-config-and-security/security": [
      {
        "api_key": []
      }
    ],
    "components": {
      "securitySchemes": {
        "api_key": {
          "type": "apiKey",
          "name": "api_key",
          "in": "header"
        }
      }
    },
    "paths": {
        "/pet": {
            "post": {
                "operationId": "addPet",
                "requestBody": {
                    "$ref": "#/components/requestBodies/Pet"
                },
                "responses": {
                    "405": {
                        "description": "Invalid input"
                    }
                },
                "summary": "Add a new pet to the store",
                "tags": [
                    "pet"
                ]
            }
        }
    }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the newly created API ID:

{
    "key": {api-id},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload your Gateway

Once you have updated your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Check your OAS API definition

Go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) and check the newly modified Tyk OAS API Definition. You’ll notice that the middleware.operations configuration has been added under the x-tyk-api-gateway section, which now tells the Gateway that the only accessible path is the one with the addPet operationId.

{
  ...
  "x-tyk-api-gateway": {
    ...
    "middleware": {
    "operations": {
      "addPet": {
        "allow": {
          "enabled": true
        }
      }
    }
  }
}

Validate API request payload

In the OAS API Definition that you updated at Update an API using just the OAS definition, you also defined a JSON schema that describes the payload format for any request that hits the POST /pet path.

You can now tell the Gateway to validate any incoming request agains the documented JSON schema. This is achieved by adding the validateRequest query parameter to the PATCH request, when updating the Tyk OAS API Definition.

Property Description
Resource URL /tyk/apis/oas/{api-id}
Method PATCH
Type None
Body OAS API Definition
Parameters Path: {api-id} Query: validateRequest
curl --location --request PATCH 'http://{your-tyk-host}:{port}/tyk/apis/oas/{API_ID}?validateRequest=true' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "info":{
     "title":"Petstore",
     "version":"1.0.0"
  },
  "openapi":"3.0.3",
  "basic-config-and-security/security":[
     {
        "api_key":[
           
        ]
     }
  ],
  "components":{
     "securitySchemes":{
        "api_key":{
           "type":"apiKey",
           "name":"api_key",
           "in":"header"
        }
     },
     "schemas":{
        "Pet":{
           "required":[
              "name"
           ],
           "type":"object",
           "properties":{
              "id":{
                 "type":"integer",
                 "format":"int64",
                 "example":10
              },
              "name":{
                 "type":"string",
                 "example":"doggie"
              },
              "category":{
                 "type":"string",
                 "example":"dog"
              },
              "status":{
                 "type":"string",
                 "description":"pet status in the store",
                 "enum":[
                    "available",
                    "pending",
                    "sold"
                 ]
              }
           }
        }
     }
  },
  "paths":{
     "/pet":{
        "post":{
           "operationId":"addPet",
           "requestBody":{
              "description":"Update an existent pet in the store",
              "content":{
                 "application/json":{
                    "schema":{
                       "$ref":"#/components/schemas/Pet"
                    }
                 }
              },
              "required":true
           },
           "responses":{
              "405":{
                 "description":"Invalid input"
              }
           },
           "summary":"Add a new pet to the store",
           "tags":[
              "pet"
           ]
        }
     }
  }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the newly created API ID:

{
    "key": {api-id},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload your Gateway

Once you have updated your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Check your OAS API definition

Go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) and check the newly modified Tyk OAS API Definition. Notice that under the middleware.operations.addPet configuration has been added the validateRequest middleware configuration that ensures the payload validation from now on.

{
  ...
  "x-tyk-api-gateway": {
    ...
    "middleware": {
    "operations": {
      "addPet": {
        ...
        "validateRequest": {
          "enabled": true,
          "errorResponseCode": 422
        }
      }
    }
  }
}

Mock response from OAS definition

In the OpenAPI definition that you updated above, you also defined a JSON schema that describes the response format for any request that hits the GET /pet/{petId} path.

Tyk Gateway can “understand” and use this schema to create a mock response for any incoming requests. This is achieved by adding the mockResponse query parameter to the PATCH request, when updating the Tyk OAS API Definition.

Property Description
Resource URL /tyk/apis/oas/{api-id}
Method PATCH
Type None
Body OAS API Definition
Parameters Path: {api-id} Query: mockResponse
curl --location --request PATCH 'http://{your-tyk-host}:{port}/tyk/apis/oas/{API_ID}?mockResponse=true' \
--header 'x-tyk-authorization: {your-secret}' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "info":{
     "title":"Petstore",
     "version":"1.0.0"
  },
  "openapi":"3.0.3",
  "basic-config-and-security/security":[
     {
        "api_key":[
           
        ]
     }
  ],
  "components":{
     "basic-config-and-security/securitySchemes":{
        "api_key":{
           "type":"apiKey",
           "name":"api_key",
           "in":"header"
        }
     },
     "schemas":{
        "Pet":{
           "required":[
              "name"
           ],
           "type":"object",
           "properties":{
              "id":{
                 "type":"integer",
                 "format":"int64",
                 "example":10
              },
              "name":{
                 "type":"string",
                 "example":"doggie"
              },
              "category":{
                 "type":"string",
                 "example":"dog"
              },
              "status":{
                 "type":"string",
                 "description":"pet status in the store",
                 "enum":[
                    "available",
                    "pending",
                    "sold"
                 ]
              }
           }
        }
     }
  },
  "paths":{
     "/pet/{petId}": {
         "get": {
            "tags": [
                  "pet"
            ],
            "summary": "Find pet by ID",
            "description": "Returns a single pet",
            "operationId": "getPetById",
            "parameters": [
                  {
                     "name": "petId",
                     "in": "path",
                     "description": "ID of pet to return",
                     "required": true,
                     "schema": {
                        "type": "integer",
                        "format": "int64"
                     }
                  }
            ],
            "responses": {
                  "200": {
                     "description": "successful operation",
                     "content": {
                        "application/json": {
                              "schema": {
                                 "$ref": "#/components/schemas/Pet"
                              }
                        }
                     }
                  },
                  "400": {
                     "description": "Invalid ID supplied"
                  },
                  "404": {
                     "description": "Pet not found"
                  }
            },
            "security": [
                  {
                     "api_key": []
                  }
            ]
         }
      }  
   }
}'

Check request response

If the command succeeds, you will see the following response, where key contains the newly created API ID:

{
    "key": {api-id},
    "status": "ok",
    "action": "modified"
}

Restart or hot reload your Gateway

Once you have updated your API, you will need to either restart the Tyk Gateway, or issue a hot reload command with the following curl command:

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

Check your Tyk OAS API definition

Go to the /apps folder of your Tyk Gateway installation (by default in /var/tyk-gateway) and check the newly modified Tyk OAS API Definition. Notice that under the middleware.operations.addPet configuration has been added the validateRequest middleware configuration that ensures the payload validation from now on.

{
    ...
    "x-tyk-api-gateway": {
      ...
      "middleware": {
            "operations": {
           ..
           "getPetById": {
              ...
              "mockResponse": {
                     "enabled": true,
                     "fromOASExamples": {
                           "enabled": true
                     }
                  }
                }
            }
        }
    }
}

What did you just do?

You have demonstrated that by using just the OpenAPI definition, which can be either generated from your source code or created as part of design first approach using other tools, you can update and configure an existing Tyk OAS API Definition.