search

TykTechnologies / tyk-docs

Docs for Tyk Open source API gateway and API management platform. 100% Cloud native
https://tyk.io/docs/apim/open-source/installation/
Other
68 stars 152 forks source link

OAS Versioning page does not actually tell me how to do it #5476

Open jeffesp opened 1 month ago

jeffesp commented 1 month ago

Branch/Environment/Version

N/A

Relevant Document

https://tyk.io/docs/getting-started/key-concepts/oas-versioning/

Describe the error

There is not really an error, but the page does not actually tell me how to configure versioning with the API. It gives me a sample of defining a "Base API" and in that sample, assumes that I have another version of the API that I want to reference as a Child. In actual use, I am going to be:

  1. defining a Base API
  2. then defining a Child,
  3. then updating the Base to include the Child.

I have no idea how to do this from these docs. When I went to the API docs to look at requests and their parameters, I am still left wondering, as the PATCH request to /tyk/apis/oas/{api_id}/ does not mention that you can update versioning. So I think what I am left to try is:

  1. defining a Base API
  2. then defining a Child,
  3. GET the full API object for the Base
  4. Add the Child in the versioning info
  5. PUT that object back to the gateway so it will have a Child version.

But I have no idea if this will work, or when it does not, what I could possibly look at to see what is wrong.

Screenshots/Video

Additional context

andyo-tyk commented 4 weeks ago

Hi @jeffesp,

If you're not using Tyk Dashboard, then is is exactly what you need to do.

To shorten the process, you could create the child API first so that you can directly add its API Id to the versioning info of the Base API on creation. We recommend that you set the child API to internal (state.internal=true) so that it cannot be called directly, only via the Base API.

Note that you can manually select an API Id when you create the child API by providing a value in x-tyk-api-gateway.info.id in the API definition that you provide to Tyk (if this field is left empty then Tyk will automatically assign a value).

The Example Base API on the page that you linked shows the fields that you must configure in the API definition for your Base API

When you use the PATCH mechanism, this will update the OpenAPI description part of the Tyk OAS API based on the OpenAPI document you provide in the PATCH request. The versioning data is stored in the Tyk extension (x-tyk-api-gateway) and so will not be affected by the PATCH.

I hope this helps to give you confidence to configure the versioning for your API.