Update an API with OAS
Table Of Contents
Introduction
While developing APIs as developers, we often work with OAS definitions that are either generated from our codebase, or built ahead by the API designers. Tyk allows you to update/patch a Tyk API definition by providing only an OAS API definition.
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 an API using an OAS API definition
Make sure you know your 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
Create a new API by sending a minimalistic Tyk OAS API Definition https://bit.ly/39tnXgO to the Gateway API endpoint:
| Property | Description |
|---|---|
| Resource URL | /tyk/apis/oas |
| Method | POST |
| Type | None |
| Body | Tyk OAS API Definition |
| Param | 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 an API using just the OAS definition
Tyk allows you to update a Tyk OAS API definition by providing only an OAS API definition.
Let’s define a new path, POST /pet, with a schema that validates the payload it receives (requestBody.content.application/json.schema) and a new security scheme which updates your Tyk OAS API Definition with the new OAS API definition by sending a PATCH request to your Tyk Gateway.
| Property | Description |
|---|---|
| Resource URL | /tyk/apis/oas/{api-id} |
| Method | PATCH |
| Type | None |
| Body | OAS API Definition |
| Param | Path Parameter: {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 OAS definition
Previously you updated the Tyk OAS API Definition with a new OAS definition, which is describing a security mechanism. In order for your Tyk Gateway to pick that up, and start protecting API access, the authentication mechanism needs to be enabled within your Tyk configuration as well.
For that, together with the PATCH request you just performed, you’re going to add the authentication query parameter, that tells Tyk to automatically enable authentication, based on the settings in the OAS definition.
| Property | Description |
|---|---|
| Resource URL | /tyk/apis/oas/{api-id} |
| Method | PATCH |
| Type | None |
| Body | OAS API Definition |
| Param | Path Param: {api-id} Query Parameter: 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
While updating a Tyk API OAS Definition using just the OAS API Definition, you can also give instructions to the Gateway to explicitly allow access just to paths that are documented in the OAS API Definition. For that, we have to pass the allowList query parameter together with our payload.
| Property | Description |
|---|---|
| Resource URL | /tyk/apis/oas/{api-id} |
| Method | PATCH |
| Type | None |
| Body | OAS API Definition |
| Param | Path Parameter: {api-id} Query Parameter: 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 |
| Param | Path Parameter: {api-id} Query Parameter: 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
}
}
}
}
}
What did you just do?
You have demonstrated that by using the OAS API Definition, which can be either generated from your source code or created as part of design first approach, you can update or configure the Tyk OAS API Definition, with the x-tyk-api-gateway configuration.