OAS has landed!

  • Help reduce complexity and risk of error with OAS as the single source of truth; defining client, upstream and Tyk Gateway behaviour
  • Simplified API design in the editor of your choice thanks to schema validation
  • Only one call to turn your existing OAS API definition into a running API on your Tyk Gateway
  • Shiny new UI for when you want an even richer experience

Sound good? Great!

Tyk 4.1 brings the ability to define APIs in terms of the Open API Specification (OpenAPI Specification - Version 3.0.3 | Swagger) for both the open source and paid versions of Tyk.

If you have 2 minutes, why not take a look at the import in action: Importing APIs the easy way with OAS and Tyk - YouTube

Ready to get started? OpenAPI High Level Concepts will tell you everything you need to get going right away

We would love your feedback on how this works for you and anywhere we can improve or extend our OAS capabilities. To provide feedback, or ask questions, please either reply to this topic, or create a new topic with the category ‘OAS’

2 Likes

Nice! Really like the fact that we can OAS instead of proprietary JSON. How does this affect tyk-sync and tyk-operator ?

1 Like

Hi Barry,

Tyk Sync and Tyk Operator will continue to work with existing non-OAS APIs. For OAS APIs, we are currently expecting Tyk Sync support before the end of the year. We are targeting early next year for Tyk Operator to support OAS APIs. We’d love to hear more from you about how you’d be using these capabilities in the product. Would you be happy to be contacted by our research team for a short discussion?

Hi @John_Clifton,
Sorry for the slow response, have been away for a few days. We would like to use the OAS import, so that we have our API’s stored in a git repo. We are facing a few issues with the OAS import feature which hopefully can be resolved:

  1. Our git repo uses YAML format for the specs, not JSON. Not a showstopper, since we can convert using yq.
  2. We would like to use a custom golang plugin. So far we’ve not been able to configure this using x-tyk-api-gateway section, it seems not all properties we have for the regular api-definitions are available?
  3. Our plugin would need access to some configuration data. We tried to add ‘config_data’, but any unmapped or unsupported properties are simply ignored and get lost. In an ideal world, the plugin would be able to access the OAS specs directly (similar to ctx.GetDefinition(r) which is available to plugins currently. Since we can have many mappings in a single OAS document, we would prefer to access the specific endpoint (including the path, method, and any parameters). Something like ctx.getOASEndpointDefinition
  4. We would like a way to access all metadata of the endpoint, including the parameters and any custom attributes. For instance, a way to access the following configuration:
        "parameters": [
          {
            "description": "ID of pet to return",
            "in": "path",
            "name": "petId",
            "required": true,
            "schema": {
              "format": "int64",
              "type": "integer"
            },
            "x-tyk-permission": "manage",
            "x-tyk-type": "provider"
          }
        ],

In the above configuration, the parameter ‘petId’ has two custom attributes which may be access by a plugin.

Hope the above makes sense, I’m available to jump onto a meet to discuss further details.

Kind regards, Barry

Hi @Barry_Lagerweij,

Thank you for your questions.

Our git repo uses YAML format for the specs, not JSON. Not a showstopper, since we can convert using yq.

Yes, this is the correct approach for now and we’re looking at supporting YAML as a format in the future.

We would like to use a custom golang plugin. So far we’ve not been able to configure this using x-tyk-api-gateway section, it seems not all properties we have for the regular api-definitions are available?

As of now, the Tyk OAS API Definition doesn’t yet have full parity with the configuration options in the Classic API Definition. Custom middleware support, is on our radar and among our immediate priorities

Our plugin would need access to some configuration data. We tried to add ‘config_data’, but any unmapped or unsupported properties are simply ignored and get lost. In an ideal world, the plugin would be able to access the OAS specs directly (similar to ctx.GetDefinition(r) which is available to plugins currently. Since we can have many mappings in a single OAS document, we would prefer to access the specific endpoint (including the path, method, and any parameters). Something like ctx.getOASEndpointDefinition

Config data is another config option that would be added alongside the custom middleware section, and since OAS documentation is part of the OAS API Definition, you would be able in the future to grab anything you need from the OAS documentation within the plugin logic. We’ll be documenting all the options when releasing the support for custom middleware!

We would like a way to access all metadata of the endpoint, including the parameters and any custom attributes. For instance, a way to access the following configuration:

"parameters": [
          {
            "description": "ID of pet to return",
            "in": "path",
            "name": "petId",
            "required": true,
            "schema": {
              "format": "int64",
              "type": "integer"
            },
            "x-tyk-permission": "manage",
            "x-tyk-type": "provider"
          }
        ],

In the above configuration, the parameter ‘petId’ has two custom attributes which may be access by a plugin.
Hope the above makes sense, I’m available to jump onto a meet to discuss further details.
With every custom middleware you’ll have access to the path and method of the request, as well as the Tyk OAS API Definition, and based on that I think it’s easy to access any data of a path in the OAS documentation.

We really appreciate your input here Barry. It would be great if we could have a discussion about how you would like to use Tyk + OAS in general. Would you be interested if we set up some time to chat?

Are there pages missing in the Tyk OAS reference? I’m looking at OAS Reference

I see one page of stuff, but I still have no idea how to use OAS to describe my API.

I see references to “import an API”, but we are in the process of designing our API, so we have nothing to import. I think our option is to build the OAS up from scratch. Did I miss something here?

Hi,

Thank you for your question.

There are a couple of things that can help you construct an OAS API Definition. If you are wanting to build a Tyk OAS API Definition, i.e. defining both your API’s behaviour and the associated Tyk configuration, you can find a breakdown of the key Tyk configuration information that could go into the definition here: OpenAPI Low Level Concepts

There are also some walkthrough instructions you may find useful here: Create an OAS API

There is a schema available from GitHub that will plug into your editor to provide text highlighting here: GitHub - TykTechnologies/tyk-schemas: Json schemas of various json file types used by Tyk products. Use them to get autocompletion in these files. (JSON/draft-04 is currently the newest schema for OAS)

Alternatively you can get the schema from the Gateway directly via the schema endpoint (/schema). Details can be found at the bottom of this page: Tyk Gateway API.

If you are working in Visual Studio Code, we have a plugin that includes the right schema: Tyk Schemas - Visual Studio Marketplace

If you wanted to focus on just defining the behaviour of your API in the OAS definition, the import you mentioned will automatically add the Tyk configuration for you.

Please let us know if this doesn’t answer your question or if there is anything else we can help with.

Hi @John_Clifton , one thing I’ve noticed (Tyk v4.1.0): The documentation Create an OAS API mentions that’s possible to create an OAS api by copying just the api1-oas.json file to the ‘apps’ folder, and then restart Tyk. However, that does not seem to work. If I copy both the api1.json and the api1-oas.json files, then it’s fine. Also, when I import using the /tyk/apis/oas endpoint (with just the OAS spec) then it correctly generates the Tyk application-definition file (using the settings from the ‘x-tyk-api-gateway’ section in the open api spec.

Hi Barry,

Thank you for pointing this out. For the moment, the way to create an API on the open source gateway is via the ‘create’ endpoint with a complete Tyk OAS API definition (i.e. the x-tyk bits in place) or ‘import’ endpoint with an OAS API definition (i.e. no x-tyk bits) as you pointed out. We will update the docs to remove that file-based section for the time being.