From 38d5880aa4666db64cbb4c0eb6d49a9828c36b3c Mon Sep 17 00:00:00 2001 From: Angel Date: Thu, 3 Aug 2023 11:50:47 -0400 Subject: [PATCH] [Autodocs] PDK and API documentation (#5882) * PDK docs * vale * fix if_version * API specs * kong.vault fix --- api-specs/Gateway-EE/3.4/kong-ee-3.4.yaml | 126 +- api-specs/Gateway-OSS/3.4/kong-oss-3.4.yaml | 7530 +++++++++++++++++ app/_data/docs_nav_gateway_3.4.x.yml | 2 + .../gateway/plugin-development/pdk/index.md | 2 +- .../plugin-development/pdk/kong.client.md | 35 +- .../plugin-development/pdk/kong.plugin.md | 37 + .../plugin-development/pdk/kong.request.md | 3 +- .../plugin-development/pdk/kong.service.md | 6 + .../plugin-development/pdk/kong.tracing.md | 10 + .../plugin-development/pdk/kong.vault.md | 370 + 10 files changed, 8088 insertions(+), 33 deletions(-) create mode 100644 api-specs/Gateway-OSS/3.4/kong-oss-3.4.yaml create mode 100644 app/_src/gateway/plugin-development/pdk/kong.plugin.md diff --git a/api-specs/Gateway-EE/3.4/kong-ee-3.4.yaml b/api-specs/Gateway-EE/3.4/kong-ee-3.4.yaml index c6d9aa4ee90b..4d281039deb5 100644 --- a/api-specs/Gateway-EE/3.4/kong-ee-3.4.yaml +++ b/api-specs/Gateway-EE/3.4/kong-ee-3.4.yaml @@ -16,8 +16,8 @@ components: minimum: 1 type: integer pagination-tags-filter: - description: 'A list of tags to filter the list of resources on. Multiple tags can be concatenated using '','' to mean AND or using ''/'' to mean OR.' - example: 'tag1,tag2' + description: A list of tags to filter the list of resources on. Multiple tags can be concatenated using ',' to mean AND or using '/' to mean OR. + example: tag1,tag2 in: query name: tags schema: @@ -226,6 +226,56 @@ components: schema: type: string schemas: + ACL: + example: + consumer: + id: 84a73fb8-50fc-44a7-a4d5-aa17728ee83f + group: foo + id: b1f34145-0343-41a4-9602-4c69dec2f269 + properties: + consumer: + additionalProperties: false + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + group: + type: string + id: + type: string + tags: + items: + type: string + type: array + type: object + API-key: + example: + consumer: + id: 84a73fb8-50fc-44a7-a4d5-aa17728ee83f + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: IL1deIyHyQA40WpeLeA1bIUXuvTwlGjo + properties: + consumer: + additionalProperties: false + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + key: + type: string + tags: + items: + type: string + type: array + type: object Basic-auth-credential: example: consumer: @@ -268,7 +318,7 @@ components: description: PEM-encoded public certificate of the CA. type: string cert_digest: - description: 'SHA256 hex digest of the public certificate. This field is read-only and it cannot be set by the caller, the value is automatically computed.' + description: SHA256 hex digest of the public certificate. This field is read-only and it cannot be set by the caller, the value is automatically computed. type: string created_at: description: Unix epoch when the resource was created. @@ -295,10 +345,10 @@ components: -----END PRIVATE KEY----- properties: cert: - description: 'PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + description: PEM-encoded public certificate chain of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). type: string cert_alt: - description: 'PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). type: string created_at: description: Unix epoch when the resource was created. @@ -306,22 +356,25 @@ components: id: type: string key: - description: 'PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + description: PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). type: string key_alt: - description: 'PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + description: PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format). type: string tags: description: An optional set of strings associated with the Certificate for grouping and filtering. items: type: string type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer type: object Consumer: - description: 'The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.' + description: The Consumer object represents a consumer - or a user - of a Service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore. example: custom_id: '4200' - id: 8a388226-80e8-4027-a486-25e4f72db5d21 + id: 8a388226-80e8-4027-a486-25e4f7db5d21 tags: - silver-tier username: bob-the-builder @@ -339,6 +392,9 @@ components: items: type: string type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer username: description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. type: string @@ -425,7 +481,7 @@ components: type: object title: Key-set Plugin: - description: 'A plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a plugin Configuration to a Service, every request made by a client to that Service will run said plugin. If a plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields.' + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields. example: config: anonymous: null @@ -446,11 +502,11 @@ components: - https properties: config: - description: 'The configuration properties for the plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/).' + description: The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/). type: object consumer: additionalProperties: false - description: 'If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.' + description: If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer. properties: id: type: string @@ -472,7 +528,7 @@ components: id: type: string name: - description: 'The name of the plugin that''s going to be added. Currently, the plugin must be installed in every Kong instance separately.' + description: The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately. type: string ordering: type: object @@ -482,20 +538,20 @@ components: - grpcs - http - https - description: 'A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`.' + description: A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`. items: type: string type: array route: additionalProperties: false - description: 'If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.' + description: If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the Route being used. properties: id: type: string type: object service: additionalProperties: false - description: 'If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.' + description: If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched. properties: id: type: string @@ -505,9 +561,12 @@ components: items: type: string type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer type: object Route: - description: 'Route entities define rules to match client requests. Each route is associated with a Service, and a Service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated Service. The combination of routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the route.' + description: Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated to it. Every request matching a given Route will be proxied to its associated Service. The combination of Routes and Services (and the separation of concerns between them) offers a powerful routing mechanism with which it is possible to define fine-grained entry-points in Kong leading to different upstream services of your infrastructure. You need at least one matching rule that applies to the protocol being matched by the Route. example: hosts: - foo.example.com @@ -524,62 +583,62 @@ components: description: Unix epoch when the resource was created. type: integer destinations: - description: A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + description: A list of IP destinations of incoming connections that match this Route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". items: properties: default: {} type: object type: array headers: - description: 'One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.' + description: 'One or more lists of values indexed by header name that will cause this Route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.' type: object hosts: - description: A list of domain names that match this route. Note that the hosts value is case sensitive. + description: A list of domain names that match this Route. Note that the hosts value is case sensitive. items: type: string type: array https_redirect_status_code: default: 426 - description: 'The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the route is configured to only accept the `https` protocol.' + description: 'The status code Kong responds with when all properties of a Route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the Route is configured to only accept the `https` protocol.' type: integer id: type: string methods: - description: A list of HTTP methods that match this route. + description: A list of HTTP methods that match this Route. items: type: string type: array name: - description: 'The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test".' + description: The name of the Route. Route names must be unique, and they are case sensitive. For example, there can be two different Routes named "test" and "Test". type: string path_handling: default: v0 - description: 'Controls how the Service path, route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior.' + description: Controls how the Service path, Route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior. type: string paths: - description: A list of paths that match this route. + description: A list of paths that match this Route. items: type: string type: array preserve_host: default: false - description: 'When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the Service''s `host`.' + description: When matching a Route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the Service's `host`. type: boolean protocols: default: - http - https - description: 'An array of the protocols this route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error.' + description: An array of the protocols this Route should allow. See the [Route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error. items: type: string type: array regex_priority: default: 0 - description: 'A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).' + description: A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). type: integer request_buffering: default: true - description: 'Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.' + description: Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. type: boolean response_buffering: default: true @@ -645,6 +704,9 @@ components: items: type: string type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer type: object Service: description: 'Service entities, as the name implies, are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc. The main attribute of a Service is its URL (where Kong should proxy traffic to), which can be set as a single string or by specifying its `protocol`, `host`, `port` and `path` individually. Services are associated to routes (a Service can have many routes associated with it). Routes are entry-points in Kong and define rules to match client requests. Once a route is matched, Kong proxies the request to its associated Service. See the [Proxy Reference][proxy-reference] for a detailed explanation of how Kong proxies traffic.' @@ -751,6 +813,9 @@ components: target: description: 'The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record.' type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: number upstream: additionalProperties: false properties: @@ -1025,6 +1090,9 @@ components: items: type: string type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer use_srv_name: default: false description: 'If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`.' diff --git a/api-specs/Gateway-OSS/3.4/kong-oss-3.4.yaml b/api-specs/Gateway-OSS/3.4/kong-oss-3.4.yaml new file mode 100644 index 000000000000..55e143d4684f --- /dev/null +++ b/api-specs/Gateway-OSS/3.4/kong-oss-3.4.yaml @@ -0,0 +1,7530 @@ +components: + parameters: + pagination-offset: + description: Offset from which to return the next set of resources. Use the value of the 'offset' field from the response of a list operation as input here to paginate through all the resources + in: query + name: offset + schema: + type: string + pagination-size: + description: Number of resources to be returned. + in: query + name: size + schema: + default: 100 + maximum: 1000 + minimum: 1 + type: integer + pagination-tags-filter: + description: 'A list of tags to filter the list of resources on. Multiple tags can be concatenated using '','' to mean AND or using ''/'' to mean OR.' + example: 'tag1,tag2' + in: query + name: tags + schema: + type: string + service_id_or_name: + name: service_id_or_name + description: ID **or** name of the service to lookup + example: test-service + in: path + required: true + schema: + type: string + ca_certificate_id: + name: ca_certificate_id + description: ID of the related certificate + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + certificate_id: + name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + description: The unique identifier of the Certificate to retrieve. + certificate_name_or_id: + name: certificate_name_or_id + in: path + required: true + schema: + type: string + enum: + - a3ad71a8-6685-4b03-a101-980a953544f6 + - name + example: name + description: 'The unique identifier or the `name` attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed.' + sni_name_or_id: + name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + consumer_username_or_id: + name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + plugin_id: + name: plugin_id + in: path + required: true + schema: + type: string + example: response-ratelimiting + description: The unique identifier of the Plugin to create or update. + key-set_id_or_name: + name: key-set_id_or_name + in: path + required: true + schema: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + description: The unique identifier or the `name` attribute of the Key Set that should be associated to the newly-created Key. + key_id_or_name: + name: key_id_or_name + in: path + required: true + schema: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725 + description: The unique identifier or the name of the Key to retrieve. + route_id_or_name: + name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + upstream_id_or_name: + name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + target_id_or_target: + name: target_id_or_target + in: path + required: true + schema: + type: string + example: 'example.com:8000' + description: 'The host/port combination element of the target to set as unhealthy, or the `id` of an existing target entry.' + vault_id_or_prefix: + name: vault_id_or_prefix + in: path + required: true + schema: + type: string + example: env + description: The unique identifier or the prefix of the Vault to retrieve. + tag: + name: tags + in: path + required: true + schema: + type: string + example: example + description: Tags are strings associated to entities in Kong. + log_level: + name: log_level + in: path + required: true + schema: + type: string + enum: + - info + - notice + - warn + - error + - crit + example: warn + description: Log levels are set in Kong’s configuration. Log levels increase in order of their severity + schemas: + CA-Certificate: + description: A CA certificate object represents a trusted CA. These objects are used by Kong to verify the validity of a client or server certificate. CA Certificates can be both tagged and filtered by tags. + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f260 + type: object + title: CA-Certificate + properties: + cert: + description: PEM-encoded public certificate of the CA. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + description: SHA256 hex digest of the public certificate. + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + format: uuid + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + x-examples: + 200 - list of multiple certificates: + data: + - id: 43429efd-b3a5-4048-94cb-5cc4029909bb + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + - id: d26761d5-83a4-4f24-ac6c-cff276f2b79c + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/ca_certificates?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + Certificate: + description: 'A certificate object represents a public certificate. These fields are _referenceable_, and can be stored as [secrets](http://docs.konqhq.com/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + example: + cert: |- + -----BEGIN CERTIFICATE----- + certificate-content + -----END CERTIFICATE----- + id: b2f34145-0343-41a4-9602-4c69dec2f269 + key: |- + -----BEGIN PRIVATE KEY----- + private-key-content + -----END PRIVATE KEY----- + type: object + title: Certificate + properties: + cert: + description: 'PEM-encoded public certificate chain of the SSL key This field is referenceable and can be stored in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + type: string + example: '"-----BEGIN CERTIFICATE-----\ncertificate-content\n-----END CERTIFICATE-----"' + cert_alt: + description: PEM-encoded public certificate chain of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs. + type: string + example: '"-----BEGIN CERTIFICATE-----..."' + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + description: The UUID representation of the certificate object. + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + format: uuid + key: + description: 'PEM-encoded private key of the SSL key pair. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + type: string + example: ' "-----BEGIN RSA PRIVATE KEY-----..."' + key_alt: + description: 'PEM-encoded private key of the alternate SSL key pair. This should only be set if you have both RSA and ECDSA types of certificate available and would like Kong to prefer serving using ECDSA certs when client advertises support for it. This field is _referenceable_, which means it can be securely stored as a [secret](/gateway/latest/plan-and-deploy/security/secrets-management/getting-started) in a vault. References must follow a [specific format](/gateway/latest/plan-and-deploy/security/secrets-management/reference-format).' + type: string + example: '"-----BEGIN EC PRIVATE KEY-----..."' + tags: + description: An optional set of strings associated with the Certificate for grouping and filtering. + type: array + items: + type: string + example: '["user-level", "low-priority"]' + Consumer: + description: 'The Consumer object represents a consumer - or a user - of a service. You can either rely on Kong as the primary datastore, or you can map the consumer list with your database to keep consistency between Kong and your existing primary datastore.' + example: + custom_id: '4200' + id: 8a388226-80e8-4027-a486-25e4f7db5d21 + tags: + - silver-tier + username: bob-the-builder + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + custom_id: + description: Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or `username` with the request. + type: string + id: + type: string + tags: + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + type: array + username: + description: The unique username of the Consumer. You must send either this field or `custom_id` with the request. + type: string + type: object + title: Consumer + Key: + description: 'A Key object holds a representation of asymmetric keys in various formats. When Kong or a Kong plugin requires a specific public or private key to perform certain operations, it can use this entity.' + example: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + type: object + title: Key + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the prefix of the Vault to delete. + jwk: + description: A JSON Web Key represented as a string. + type: string + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + kid: + description: A unique identifier for a key. + type: string + example: '"42"' + name: + description: The name to associate with the given keys. + type: string + example: a-key + pem: + description: A keypair in PEM format. + type: object + properties: + private_key: + type: string + example: '"-----BEGIN"' + public_key: + type: string + example: '"-----BEGIN"' + set: + additionalProperties: false + description: The id (an UUID) of the key-set with which to associate the key. + type: object + properties: + id: + type: string + example: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + tags: + description: An optional set of strings associated with the Key for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + Key-set: + type: object + title: Key-set + description: A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + id: + type: string + example: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + description: The unique identifier or the name of the Key to delete. + name: + type: string + description: The name to associate with the given key-set. + example: '"example-key-set"' + tags: + type: array + description: n optional set of strings associated with the Key for grouping and filtering + items: + type: string + example: '["google-keys", "mozilla-keys"]' + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + tags: + - idp-keys + Plugin: + description: A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. + example: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + properties: + config: + description: 'The configuration properties for the Plugin which can be found on the plugins documentation page in the [Kong Hub](https://docs.konghq.com/hub/).' + type: object + consumer: + additionalProperties: false + description: 'If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.' + properties: + id: + type: string + type: object + consumer_group: + additionalProperties: false + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + enabled: + default: true + description: Whether the plugin is applied. + type: boolean + id: + type: string + instance_name: + type: string + name: + description: 'The name of the Plugin that''s going to be added. Currently, the Plugin must be installed in every Kong instance separately.' + type: string + ordering: + type: object + protocols: + default: + - grpc + - grpcs + - http + - https + description: 'A list of the request protocols that will trigger this plugin. The default value, as well as the possible values allowed on this field, may change depending on the plugin type. For example, plugins that only work in stream mode will only support `"tcp"` and `"tls"`.' + items: + type: string + type: array + route: + additionalProperties: false + description: 'If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.' + properties: + id: + type: string + type: object + service: + additionalProperties: false + description: 'If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service. Leave unset for the plugin to activate regardless of the service being matched.' + properties: + id: + type: string + type: object + tags: + description: An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + type: array + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + type: object + title: Plugin + Route: + description: Route entities define rules to match client requests. Every request matching a given route will be proxied to its associated service. + example: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + type: object + title: Route + properties: + created_at: + description: Unix epoch when the resource was created. + type: integer + destinations: + description: A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + headers: + description: 'One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.' + type: object + hosts: + description: A list of domain names that match this route. Note that the hosts value is case sensitive. + type: array + items: + type: string + example: '"foo.example.com"' + https_redirect_status_code: + default: 426 + description: 'The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the route is configured to only accept the `https` protocol.' + type: integer + id: + type: string + example: 56c4566c-14cc-4132-9011-4139fcbbe50a + methods: + description: A list of HTTP methods that match this route. + type: array + items: + type: string + name: + description: 'The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named "test" and "Test".' + type: string + path_handling: + default: v0 + description: 'Controls how the service path, route path and requested path are combined when sending a request to the upstream. See above for a detailed description of each behavior.' + type: string + paths: + description: A list of paths that match this route. + type: array + items: + type: string + preserve_host: + default: false + description: 'When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the service''s `host`.' + type: boolean + protocols: + default: + - http + - https + description: 'An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `"https"`, HTTP requests are answered with an upgrade error. When set to only `"http"`, HTTPS requests are answered with an error.' + type: array + items: + type: string + regex_priority: + default: 0 + description: 'A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).' + type: integer + request_buffering: + default: true + description: 'Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.' + type: boolean + response_buffering: + default: true + description: 'Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.' + type: boolean + service: + additionalProperties: false + description: The service this route is associated to. This is where the route proxies traffic to. + type: object + properties: + id: + type: string + snis: + description: A list of SNIs that match this route when using stream routing. + type: array + items: + type: string + sources: + description: A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields "ip" (optionally in CIDR range notation) and/or "port". + type: array + items: + type: object + properties: + '': {} + strip_path: + default: true + description: 'When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL.' + type: boolean + tags: + description: An optional set of strings associated with the route for grouping and filtering. + type: array + items: + type: string + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + SNI: + description: 'An SNI object represents a many-to-one mapping of hostnames to a certificate. That is, a certificate object can have many hostnames associated with it; when Kong receives an SSL request, it uses the SNI field in the Client Hello to lookup the certificate object based on the SNI associated with the certificate.' + example: + certificate: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + id: 36c4566c-14cc-4132-9011-4139fcbbe50a + name: some.example.org + type: object + properties: + certificate: + additionalProperties: false + description: The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + id: + type: string + example: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: + description: The SNI name to associate with the given certificate. + type: string + example: my-sni + tags: + description: An optional set of strings associated with the SNIs for grouping and filtering. + type: array + items: + type: string + example: 'user-level, enterprise' + Service: + description: 'service entities are abstractions of upstream services. The main attribute of a service is its URL which can be set as a single string or by specifying the `protocol`, `host`, `port` and `path` individually.' + example: + host: example.internal + id: 49fd316e-c457-481c-9fc7-8079153e4f3c + name: example-service + path: / + port: 80 + protocol: http + type: object + properties: + ca_certificates: + description: 'Array of `CA Certificate` object UUIDs that are used to build the trust store while verifying upstream server''s TLS certificate. If set to `null` when Nginx default is respected. If default CA list in Nginx are not specified and TLS verification is enabled, then handshake with upstream server will always fail (because no CA are trusted).' + type: array + items: + type: string + client_certificate: + additionalProperties: false + description: Certificate to be used as client certificate while TLS handshaking to the upstream server. + type: object + properties: + id: + type: string + connect_timeout: + default: 60000 + description: The timeout in milliseconds for establishing a connection to the upstream server. + type: integer + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + enabled: + default: true + description: 'Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`.' + type: boolean + host: + description: The host of the upstream server. Note that the host value is case sensitive. + type: string + id: + type: string + name: + description: The service name. + type: string + path: + description: The path to be used in requests to the upstream server. + type: string + port: + default: 80 + description: The upstream server port. + type: integer + protocol: + default: http + description: The protocol used to communicate with the upstream. + type: string + read_timeout: + default: 60000 + description: The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. + type: integer + retries: + default: 5 + description: The number of retries to execute upon failure to proxy. + type: integer + tags: + description: An optional set of strings associated with the service for grouping and filtering. + type: array + items: + type: string + tls_verify: + description: 'Whether to enable verification of upstream server TLS certificate. If set to `null`, then the Nginx default is respected.' + type: boolean + tls_verify_depth: + description: 'Maximum depth of chain while verifying Upstream server''s TLS certificate. If set to `null`, then the Nginx default is respected.' + type: integer + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + url: + description: 'Helper field to set `protocol`, `host`, `port` and `path` using a URL. This field is write-only and is not returned in responses.' + type: string + write_timeout: + default: 60000 + description: The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. + type: integer + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + title: Service + Target: + description: 'A target is an ip address/hostname with a port that identifies an instance of a backend service. Every upstream can have many targets, and the targets can be dynamically added, modified, or deleted. Changes take effect on the fly. To disable a target, post a new one with `weight=0`; alternatively, use the `DELETE` convenience method to accomplish the same. The current target object definition is the one with the latest `created_at`.' + example: + id: 089292a7-ba3d-4d88-acf0-97b4b2e2621a + target: 203.0.113.42 + upstream: + id: 5f1d7e76-2fed-4806-a6af-869984f025cb + weight: 100 + type: object + properties: + created_at: + description: Unix epoch when the resource was created. + type: number + example: 1422386534 + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + tags: + description: An optional set of strings associated with the Target for grouping and filtering. + type: array + items: + type: string + target: + description: 'The target address (ip or hostname) and port. If the hostname resolves to an SRV record, the `port` value will be overridden by the value from the DNS record.' + type: string + upstream: + additionalProperties: false + type: object + description: The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + weight: + default: 100 + description: 'The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record.' + type: integer + example: 100 + x-examples: + Example 1: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + Upstream: + description: 'The upstream object represents a virtual hostname and can be used to loadbalance incoming requests over multiple services (targets). So for example an upstream named `service.v1.xyz` for a service object whose `host` is `service.v1.xyz`. Requests for this service would be proxied to the targets defined within the upstream. An upstream also includes a [health checker][healthchecks], which is able to enable and disable targets based on their ability or inability to serve requests. The configuration for the health checker is stored in the upstream object, and applies to all of its targets.' + example: + algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + properties: + algorithm: + default: round-robin + description: Which load balancing algorithm to use. + type: string + client_certificate: + additionalProperties: false + description: 'If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.' + properties: + id: + type: string + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + hash_fallback: + default: none + description: 'What to use as hashing input if the primary `hash_on` does not return a hash (eg. header is missing, or no Consumer identified). Not available if `hash_on` is set to `cookie`.' + type: string + hash_fallback_header: + description: The header name to take the value from as hash input. Only required when `hash_fallback` is set to `header`. + type: string + hash_fallback_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + type: string + hash_fallback_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + type: string + hash_on: + default: none + description: What to use as hashing input. Using `none` results in a weighted-round-robin scheme with no hashing. + type: string + hash_on_cookie: + description: 'The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.' + type: string + hash_on_cookie_path: + default: / + description: The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. + type: string + hash_on_header: + description: The header name to take the value from as hash input. Only required when `hash_on` is set to `header`. + type: string + hash_on_query_arg: + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + type: string + hash_on_uri_capture: + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + type: string + healthchecks: + properties: + active: + properties: + concurrency: + default: 10 + type: integer + headers: + type: object + healthy: + properties: + http_statuses: + default: + - 200 + - 302 + items: + type: integer + type: array + interval: + default: 0 + type: number + successes: + default: 0 + type: integer + type: object + http_path: + default: / + type: string + https_sni: + type: string + https_verify_certificate: + default: true + type: boolean + timeout: + default: 1 + type: number + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + items: + type: integer + type: array + interval: + default: 0 + type: number + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + passive: + properties: + healthy: + properties: + http_statuses: + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + items: + type: integer + type: array + successes: + default: 0 + type: integer + type: object + type: + default: http + type: string + unhealthy: + properties: + http_failures: + default: 0 + type: integer + http_statuses: + default: + - 429 + - 500 + - 503 + items: + type: integer + type: array + tcp_failures: + default: 0 + type: integer + timeouts: + default: 0 + type: integer + type: object + type: object + threshold: + default: 0 + type: number + type: object + host_header: + description: The hostname to be used as `Host` header when proxying requests through Kong. + type: string + id: + type: string + name: + description: 'This is a hostname, which must be equal to the `host` of a service.' + type: string + slots: + default: 10000 + description: 'The number of slots in the load balancer algorithm. If `algorithm` is set to `round-robin`, this setting determines the maximum number of slots. If `algorithm` is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range `10`-`65536`.' + type: integer + tags: + description: An optional set of strings associated with the Upstream for grouping and filtering. + items: + type: string + type: array + use_srv_name: + default: false + description: 'If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream `Host`.' + type: boolean + type: object + Vault: + description: 'Vault entities are used to configure different Vault connectors. Examples of Vaults are Environment Variables, Hashicorp Vault and AWS Secrets Manager. Configuring a Vault allows referencing the secrets with other entities. For example a certificate entity can store a reference to a certificate and key, stored in a vault, instead of storing the certificate and key within the entity. This allows a proper separation of secrets and configuration and prevents secret sprawl.' + example: + config: + prefix: ENV_PREFIX + description: environment variable based vault + id: 2747d1e5-8246-4f65-a939-b392f1ee17f8 + name: env + tags: + - foo + - bar + type: object + properties: + config: + description: The configuration properties for the Vault which can be found on the vaults' documentation page. + type: object + created_at: + description: Unix epoch when the resource was created. + type: integer + example: 1422386534 + description: + description: The description of the Vault entity. + type: string + example: This vault is used to retrieve redis database access credentials + id: + type: string + example: B2A30E8F-C542-49CF-8015-FB674987D1A5 + name: + description: 'The name of the Vault that''s going to be added. Currently, the Vault implementation must be installed in every Kong instance.' + type: string + example: env + prefix: + description: The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + type: string + example: env + tags: + description: An optional set of strings associated with the Vault for grouping and filtering. + type: array + items: + type: string + example: database-credentials + updated_at: + description: Unix epoch when the resource was last updated. + type: integer + example: 1422386534 + x-examples: + Example Vault: + id: B2A30E8F-C542-49CF-8015-FB674987D1A5 + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + created_at: 1422386534 + updated_at: 1422386534 + tags: + - database-credentials + - data-plane + pagination-offset-response: + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + type: string + requestBodies: + CA-cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + cert: '-----BEGIN CERTIFICATE-----...' + cert_digest: c641e28d77e93544f2fa87b2cf3f3d51... + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: | + PEM-encoded public certificate of the CA. + example: '"-----BEGIN CERTIFICATE-----..."' + cert_digest: + type: string + example: c641e28d77e93544f2fa87b2cf3f3d51... + description: | + SHA256 hex digest of the public certificate. + tags: + type: array + description: An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + required: + - cert + description: This request body represents a new Certificate Authority (CA) certificate and includes the properties required to create a new certificate. + cert-request: + content: + application/json: + schema: + type: object + x-examples: + Example: + id: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + created_at: 1422386534 + cert: '-----BEGIN CERTIFICATE-----...' + key: '-----BEGIN RSA PRIVATE KEY-----...' + cert_alt: '-----BEGIN CERTIFICATE-----...' + key_alt: '-----BEGIN EC PRIVATE KEY-----...' + snis: + - foo.test + - example.com + tags: + - user-level + - low-priority + properties: + cert: + type: string + description: 'PEM-encoded public certificate chain of the SSL key pair. ' + example: '"-----BEGIN CERTIFICATE-----...",' + key: + type: string + example: '"-----BEGIN RSA PRIVATE KEY-----..."' + description: 'PEM-encoded private key of the SSL key pair. ' + cert_alt: + type: string + description: 'PEM-encoded public certificate chain of the alternate SSL key pair. ' + key_alt: + type: string + description: 'PEM-encoded private key of the alternate SSL key pair. ' + example: '"-----BEGIN EC PRIVATE KEY-----..."' + snis: + type: array + description: An array of zero or more hostnames to associate with this certificate as SNIs. + items: + type: string + tags: + type: array + description: | + An optional set of strings associated with the Certificate for grouping and filtering. + items: + type: string + passphrase: + type: string + description: 'To load an encrypted private key into Kong, specify the passphrase using this attributKong will decrypt the private key and store it in its database. e. Enterprise Only' + example: example + required: + - cert + - key + create-sni: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-sni + tags: + - user-level + - low-priority + certificate: + id: a2e013e8-7623-4494-a347-6d29108ff68b + properties: + name: + type: string + description: The SNI name to associate with the given certificate. + example: my-sni + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + example: '["user-level", "low-priority"]' + certificate: + type: object + description: 'The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. With form-encoded, the notation is `certificate.id=`. With JSON, use `“certificate":{"id":"”}`.' + properties: + id: + type: string + example: 91020192-062d-416f-a275-9addeeaffaf2 + description: 91020192-062d-416f-a275-9addeeaffaf2 + required: + - name + - certificate + description: 'A JSON object containing the details of the new SNI, including the name, certificate, and tags.' + consumer-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + username: + type: string + description: | + The unique username of the Consumer. You must send either this field or custom_id with the request. + custom_id: + type: string + description: | + Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. You must send either this field or username with the request. + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + required: + - username + - custom_id + description: Consumer request body + plugin-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: rate-limiting + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + properties: + name: + type: string + description: 'The name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.' + example: rate-limiting + route: + type: string + description: 'If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default: `null`.With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`.' + nullable: true + service: + type: string + description: 'If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service.' + nullable: true + consumer: + type: string + description: 'If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.)' + nullable: true + instance_name: + type: string + description: | + The Plugin instance name. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: |- + Describes a dependency to another plugin to determine plugin ordering during the access phase. + –`before`: The plugin will be executed before a specified plugin or list of plugins. + – `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + examples: + request example: + value: + name: rate-limiting + route: string + service: string + consumer: string + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 500 + protocols: + - http + enabled: true + tags: + - string + ordering: + before: + - string + description: Plugin request body + key-set-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-key_set + tags: + - google-keys + - mozilla-keys + properties: + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + keys-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + properties: + set: + type: object + description: 'The id (an UUID) of the key-set with which to associate the key .With form-encoded, the notation is `set.id=` or `set.name=`. With JSON, use `“"set":{"id":""}` or `"set":{"name":""}.`' + properties: + id: + type: string + description: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: + type: string + example: my-key + description: | + The name to associate with the given keys. + kid: + type: string + description: | + A unique identifier for a key. + example: '42' + jwk: + type: string + description: A JSON Web Key represented as a string. + example: '{\"alg\":\"RSA\", \"kid\": \"42\", ...}' + pem: + type: object + description: | + A keypair in PEM format. + properties: + private_key: + type: string + example: 'private_key": "-----BEGIN' + public_key: + type: string + example: 'public_key": "-----BEGIN' + tags: + type: array + description: | + An optional set of strings associated with the Key for grouping and filtering. + items: + type: string + required: + - kid + route-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + snis: + - foo.test + - example.com + sources: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + destinations: + - ip: 10.1.0.0/16 + port: 1234 + - ip: 10.2.2.2 + - port: 9123 + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + properties: + name: + type: string + description: | + The name of the route. Route names must be unique, and they are case sensitive. For example, there can be two different routes named “test” and “Test”. + protocols: + type: array + description: An array of the protocols this route should allow + items: + type: string + default: https + example: tcp + methods: + type: array + description: | + A list of HTTP methods that match this route. + items: + type: string + example: GET + hosts: + type: array + description: 'A list of domain names that match this route. Note that the hosts value is case sensitive. With form-encoded, the notation is `hosts[]=example.com&hosts[]=foo.test`. With JSON, use an Array.' + items: + type: string + paths: + type: array + description: 'A list of paths that match this route. With form-encoded, the notation is `paths[]=/foo&paths[]=/bar`. With JSON, use an array. The path can be a regular expression, or a plain text pattern. ' + items: + type: string + headers: + type: object + description: 'One or more lists of values indexed by header name that will cause this route to match if present in the request. The Host header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When headers contains only one value and that value starts with the special prefix` ~*`, the value is interpreted as a regular expression.' + properties: + x-my-header: + type: array + items: + type: string + x-another-header: + type: array + items: + type: string + https_redirect_status_code: + type: integer + description: |- + The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS` + Location header is injected by Kong if the field is set to `301`, `302`, `307` or `308`. Note: This config applies only if the route is configured to only accept the https protocol. Accepted values are: `426`, `301`, `302`, `307`, `308`. Default: `426`. + default: 426 + enum: + - 426 + - 301 + - 302 + - 307 + - 308 + example: 426 + regex_priority: + type: integer + description: 'A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same regex_priority, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones). Default: `0`.' + default: 0 + example: 0 + strip_path: + type: boolean + description: 'When matching a route via one of the paths, strip the matching prefix from the upstream request URL. Default: `true`.' + default: true + path_handling: + type: string + description: 'Controls how the service path, route path and requested path are combined when sending a request to the upstream. Accepted values are: "`v0`", "`v1`". Default: "`v0`".' + enum: + - v1 + - v0 + example: v0 + preserve_host: + type: boolean + description: 'When matching a route via one of the `hosts` domain names, use the request `host` header in the upstream request headers. If set to `false`, the upstream Host header will be that of the service’s host.' + default: true + request_buffering: + type: boolean + default: true + description: | + Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding. Default: true. + response_buffering: + type: boolean + default: true + description: | + Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding. Default: `true`. + snis: + type: array + description: | + A list of SNIs that match this route when using stream routing. + items: + type: string + sources: + type: array + description: | + A list of IP sources of incoming connections that match this route when using stream routing. Each entry is an object with fields “ip” (optionally in CIDR range notation) and/or “port”. + items: + type: object + properties: + ip: + type: string + example: 10.1.0.0/16 + port: + type: integer + example: 1234 + destinations: + type: array + description: | + A list of IP destinations of incoming connections that match this route when using stream routing. Each entry is an object with fields “ip” (optionally in CIDR range notation) and/or “port”. + items: + type: object + properties: + ip: + type: string + example: 0.1.0.0/16 + port: + type: integer + tags: + type: array + description: | + An optional set of strings associated with the route for grouping and filtering. + items: + type: string + service: + type: object + description: |- + + The service this route is associated to. This is where the route proxies traffic to. With form-encoded, the notation is service.id= or service.name=. With JSON, use “`"service":{"id":""}` or `"service":{"name":""}`. + properties: + id: + type: string + example: af8330d3-dbdc-48bd-b1be-55b98608834b + required: + - protocols + - https_redirect_status_code + - preserve_host + - request_buffering + - response_buffering + examples: + Create a route: + value: + name: my-route + protocols: + - http + - https + methods: + - GET + - POST + hosts: + - example.com + - foo.test + paths: + - /foo + - /bar + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + https_redirect_status_code: 426 + regex_priority: 0 + strip_path: true + path_handling: v0 + preserve_host: false + request_buffering: true + response_buffering: true + tags: + - user-level + - low-priority + service: + id: af8330d3-dbdc-48bd-b1be-55b98608834b + description: Route request body + service-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 9748f662-7711-4a90-8186-dc02f10eb0f5 + created_at: 1422386534 + updated_at: 1422386534 + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 60000 + write_timeout: 60000 + read_timeout: 60000 + tags: + - user-level + - low-priority + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515 + enabled: true + properties: + name: + type: string + description: | + The service name. + example: my-service + retries: + type: integer + description: | + The number of retries to execute upon failure to proxy. Default:`5`. + default: 5 + example: 5 + protocol: + type: string + description: |- + + The protocol used to communicate with the upstream. Accepted values are: "`grpc`", "`grpcs`", "`http`", "`https`", "`tcp`", "`tls`", "`tls_passthrough`", "`udp`", "`ws`" + , "`wss`" + . Default: "`http`". + default: http + enum: + - grpc + - grpcs + - http + - https + - tcp + - 'tls ' + - tls_passthrough + - udp + - ws + - wss + example: http + host: + type: string + description: | + The host of the upstream server. Note that the host value is case sensitive. + example: example.com + port: + type: integer + description: | + The upstream server port. Default: `80`. + default: 80 + example: 80 + path: + type: string + description: | + The path to be used in requests to the upstream server. + example: /some_api + connect_timeout: + type: integer + description: 'The timeout in milliseconds for establishing a connection to the upstream server. Default: `60000`.' + default: 6000 + example: 6000 + write_timeout: + type: integer + description: | + The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + read_timeout: + type: integer + description: | + The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server. Default: `60000`. + default: 6000 + example: 6000 + tags: + type: array + description: | + An optional set of strings associated with the service for grouping and filtering. + items: + type: string + example: user-level + client_certificate: + type: object + description: 'Certificate to be used as client certificate while TLS handshaking to the upstream server. With form-encoded, the notation is `client_certificate.id=`. With JSON, use `"client_certificate":{"id":""}`.' + properties: + id: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: + type: boolean + description: | + Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected. + default: true + tls_verify_depth: + type: string + description: | + Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected. Default: null. + example: respected + default: null + nullable: true + ca_certificates: + type: array + description: 'Array of CA Certificate object UUIDs that are used to build the trust store while verifying upstream server’s TLS certificate. If set to null when Nginx default is respected. With form-encoded, the notation is `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`. With JSON, use an Array.' + items: + type: string + example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: + type: boolean + default: true + description: 'Whether the service is active. If set to `false`, the proxy behavior will be as if any routes attached to it do not exist (404). Default: `true`.' + required: + - protocol + - host + - port + - enabled + examples: + Example: + value: + name: my-service + retries: 5 + protocol: http + host: example.com + port: 80 + path: /some_api + connect_timeout: 6000 + write_timeout: 6000 + read_timeout: 6000 + tags: + - user-level + client_certificate: + id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + tls_verify: true + tls_verify_depth: null + ca_certificates: + - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b + enabled: true + upstream-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + - x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + properties: + name: + type: string + description: 'This is a hostname, which must be equal to the `host` of a service.' + example: my-upstream + algorithm: + type: string + description: | + Which load balancing algorithm to use. Accepted values are: `"consistent-hashing"`, `"least-connections"`,` "round-robin"`. Default: `"round-robin"`. + enum: + - consistent-hashing + - least-connections + - round-robin + - latency + default: round-robin + example: round-robin + hash_on: + type: string + description: What to use as hashing input. Using none results in a weighted-round-robin scheme with no hashing + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + hash_fallback: + type: string + description: 'What to use as hashing input if the primary hash_on does not return a hash (eg. header is missing, or no Consumer identified). Not available if hash_on is set to cookie.' + default: none + enum: + - none + - consumer + - ip + - cookie + - uri_capture + - path + - query_arg + example: none + hash_on_header: + type: string + description: The header name to take the value from as hash input. Only required when `hash_on` is set to header. + example: none + hash_fallback_header: + type: string + description: The header name to take the value from as hash input. Only required when hash_fallback is set to header. + default: none + example: none + hash_on_cookie: + type: string + description: 'The cookie name to take the value from as hash input. Only required when `hash_on` or `hash_fallback` is set to `cookie`. If the specified cookie is not in the request, Kong will generate a value and set the cookie in the response.' + example: none + hash_on_cookie_path: + type: string + description: 'The cookie path to set in the response headers. Only required when `hash_on` or `hash_fallback` is set to `cookie`. Default: `/`.' + default: / + example: / + hash_on_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_on` is set to `query_arg`. + example: hash_value + hash_fallback_query_arg: + type: string + description: The name of the query string argument to take the value from as hash input. Only required when `hash_fallback` is set to `query_arg`. + example: hash_value + hash_on_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_on` is set to `uri_capture`. + example: hash_value + hash_fallback_uri_capture: + type: string + description: The name of the route URI capture to take the value from as hash input. Only required when `hash_fallback` is set to `uri_capture`. + example: hash_value + slots: + type: integer + description: 'The number of slots in the load balancer algorithm. If the algorithm is set to `round-robin`, this setting determines the maximum number of slots. If the algorithm is set to `consistent-hashing`, this setting determines the actual number of slots in the algorithm. Accepts an integer in the range 10-65536.' + minimum: 10 + maximum: 65536 + default: 10000 + example: 5000 + healthchecks: + type: object + properties: + passive: + type: object + properties: + type: + type: string + description: 'Whether to perform passive health checks interpreting HTTP/HTTPS statuses, or just check for TCP connection success. In passive checks, http and https options are equivalent. Accepted values are: `tcp`, `http`, `https`, `grpc`, `grpcs`.' + default: http + enum: + - tcp + - http + - https + - grpc + - grpcs + example: tcp + healthy: + type: object + properties: + http_statuses: + type: array + description: 'An array of HTTP statuses which represent healthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=201`. With JSON, use an array.' + default: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + example: + - 200 + - 201 + - 202 + items: + type: integer + enum: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: + type: integer + description: 'Number of successes in proxied traffic (as defined by `healthchecks.passive.healthy.http_statuses`) to consider a target healthy, as observed by passive health checks.' + default: 0 + example: 2 + unhealthy: + type: object + properties: + http_statuses: + type: array + description: 'An array of HTTP statuses which represent unhealthiness when produced by proxied traffic, as observed by passive health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=500`. With JSON, use an array.' + default: + - 429 + - 500 + - 503 + example: + - 500 + - 503 + items: + type: integer + enum: + - 429 + - 500 + - 503 + timeouts: + type: integer + description: 'Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks.' + default: 0 + example: 1 + http_failures: + type: integer + description: 'Number of HTTP failures in proxied traffic (as defined by `healthchecks.passive.unhealthy.http_statuses`) to consider a target unhealthy, as observed by passive health checks.' + default: 0 + example: 3 + tcp_failures: + type: integer + description: 'Number of TCP connection failures to consider a target unhealthy, as observed by passive health checks.' + default: 0 + example: 1 + active: + type: object + properties: + https_verify_certificate: + type: boolean + healthy: + type: object + properties: + http_statuses: + type: array + description: 'An array of HTTP statuses to consider a success, indicating healthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=200&http_statuses[]=302`. With JSON, use an array.' + default: + - 200 + - 302 + example: + - 200 + - 201 + items: + type: integer + successes: + type: integer + description: Number of successes in active probes (as defined by `healthchecks.active.healthy.http_statuses`) to consider a target healthy. + default: 0 + example: 3 + interval: + type: integer + description: Interval between active health checks for healthy targets (in seconds). A value of zero indicates that active probes for healthy targets should not be performed. + default: 0 + example: 30 + unhealthy: + type: object + properties: + http_failures: + type: integer + description: Number of HTTP failures in active probes (as defined by `healthchecks.active.unhealthy.http_statuses`) to consider a target unhealthy. + default: 0 + example: 2 + http_statuses: + type: array + description: 'An array of HTTP statuses to consider a failure, indicating unhealthiness, when returned by a probe in active health checks. With form-encoded, the notation is `http_statuses[]=429&http_statuses[]=404`. With JSON, use an array.' + default: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + example: + - 400 + - 404 + items: + type: integer + timeouts: + type: integer + description: Number of timeouts in active probes to consider a target unhealthy. + default: 0 + example: 2 + tcp_failures: + type: integer + description: Number of TCP failures in active probes to consider a target unhealthy. + default: 0 + example: 1 + interval: + type: integer + description: Interval between active health checks for unhealthy targets (in seconds). A value of zero indicates that active probes for unhealthy targets should not be performed. + default: 0 + example: 10 + type: + type: string + description: 'Whether to perform active health checks using HTTP or HTTPS, or just attempt a TCP connection.' + enum: + - tcp + - http + - https + - grpc + - grpcs + default: http + example: https + concurrency: + type: integer + description: Number of targets to check concurrently in active health checks. + default: 10 + example: 5 + headers: + type: object + description: One or more lists of values indexed by header name to use in GET HTTP request to run as a probe on active health checks. Values must be pre-formatted. + example: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: + type: integer + description: Socket timeout for active health checks (in seconds). + default: 1 + example: 5 + http_path: + type: string + description: Path to use in GET HTTP request to run as a probe on active health checks. + default: / + https_sni: + type: string + description: 'The hostname to use as an SNI (Server Name Identification) when performing active health checks using HTTPS. This is particularly useful when Targets are configured using IPs, so that the target host’s certificate can be verified with the proper SNI.' + threshold: + type: integer + description: The minimum percentage of the upstream’s targets’ weight that must be available for the whole upstream to be considered healthy. + minimum: 0 + maximum: 100 + default: 0 + tags: + type: array + description: An optional set of strings associated with the Upstream for grouping and filtering. + example: + - user-level + - low-priority + items: + type: string + host_header: + type: string + description: The hostname to be used as Host header when proxying requests through Kong. + client_certificate: + type: object + description: 'If set, the certificate to be used as client certificate while TLS handshaking to the upstream server.' + properties: + id: + type: string + example: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: + type: boolean + description: 'If set, the balancer will use SRV hostname(if DNS Answer has SRV record) as the proxy upstream Host.' + example: false + required: + - name + examples: + Upstream: + value: + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + Example request: + value: + name: my-upstream + tags: + - user-level + - low-priority + algorithm: round-robin + target-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + properties: + upstream: + type: object + description: | + The unique identifier or the name of the upstream for which to update the target. + properties: + id: + type: string + example: 173a6cee-90d1-40a7-89cf-0329eca780a6 + description: The unique identifier or the name of the upstream for which to update the target. + weight: + default: 100 + description: 'The weight this target gets within the upstream loadbalancer (`0`-`65535`). If the hostname resolves to an SRV record, the `weight` value will be overridden by the value from the DNS record.' + type: integer + minimum: 0 + maximum: 65535 + tags: + type: array + description: An optional set of strings associated with the Target for grouping and filtering. + items: + type: string + examples: + Example: + value: + upstream: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + weight: 100 + tags: + - string + vault-request: + content: + application/json: + schema: + type: object + x-examples: + Example 1: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + properties: + prefix: + type: string + description: | + The unique prefix (or identifier) for this Vault configuration. The prefix is used to load the right Vault configuration and implementation when referencing secrets with the other entities. + example: env + name: + type: string + description: | + The name of the Vault that’s going to be added. Currently, the Vault implementation must be installed in every Kong instance. + example: env + description: + type: string + description: | + The description of the Vault object. + example: This vault is used to retrieve redis database access credentials + config: + type: object + description: | + The configuration properties for the Vault which can be found on the vaults’ documentation page. + properties: + prefix: + type: string + example: SSL_ + tags: + type: array + description: | + An optional set of strings associated with the Vault for grouping and filtering. + items: + type: string + examples: + Example 1: + value: + prefix: env + name: env + description: This vault is used to retrieve redis database access credentials + config: + prefix: SSL_ + tags: + - database-credentials + - data-plane + responses: + sni-response: + description: SNI response object + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + name: my-sni + created_at: 1422386534 + tags: + - user-level + - low-priority + certificate: + id: a3ad71a8-6685-4b03-a101-980a953544f6 + - id: b87eb55d-69a1-41d2-8653-8d706eecefc0 + name: my-sni + created_at: 1422386534 + tags: + - admin + - high-priority + - critical + certificate: + id: 4e8d95d4-40f2-4818-adcb-30e00c349618 + next: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + description: Array of SNIs + items: + type: object + properties: + id: + type: string + example: 147f5ef0-1ed6-4711-b77f-489262f8bff7 + description: 'The unique identifier or the name attribute of the Certificate whose SNIs are to be retrieved. When using this endpoint, only SNIs associated to the specified Certificate will be listed.' + name: + type: string + description: | + The SNI name to associate with the given certificate. + example: my-sni + created_at: + type: integer + example: 1422386534 + description: |+ + Unix epoch when the resource was created. + + tags: + type: array + description: | + An optional set of strings associated with the SNIs for grouping and filtering. + items: + type: string + certificate: + type: object + description: |+ + The id (a UUID) of the certificate with which to associate the SNI hostname. The Certificate must have a valid private key associated with it to be used by the SNI object. + + properties: + id: + type: string + example: 2e013e8-7623-4494-a347-6d29108ff68b + description: The unique identifier or the name attribute of the Certificate whose SNIs + next: + type: string + example: 'http://localhost:8001/snis?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + description: Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + consumer-response-data: + description: The consumer object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - id: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + - id: 01c23299-839c-49a5-a6d5-8864c09184af + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - admin + - high-priority + - critical + next: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + data: + type: array + items: + type: object + properties: + id: + type: string + description: The unique identifier or the name attribute of the consumer. + example: a4407883-c166-43fd-80ca-3ca035b0cdb7 + created_at: + type: integer + description: Unix epoch when the resource was created. + example: 1422386534 + username: + type: string + description: The unique username of the consumer. You must send either this field or` custom_i`d with the request. + example: my-username + custom_id: + type: string + description: Field for storing an existing unique ID for the Consumer - useful for mapping Kong with users in your existing database. + example: my-custom-id + tags: + type: array + description: | + An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + example: admin + next: + type: string + description: Pagination information + example: 'http://localhost:8001/consumers?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + consumer-create-response: + description: New consumer created response + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: ec1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: 1422386534 + username: my-username + custom_id: my-custom-id + tags: + - user-level + - low-priority + properties: + id: + type: string + description: The unique id of the consumer. + example: c1a1f6f-2aa4-4e58-93ff-b56368f19b27 + created_at: + type: integer + description: |+ + Unix epoch when the resource was created. + + username: + type: string + description: The unique username of the consumer. + custom_id: + type: string + description: Field for the unique consumer ID + tags: + type: array + description: An optional set of strings associated with the Consumer for grouping and filtering. + items: + type: string + plugin-response: + description: Example response + content: + application/json: + schema: + type: object + properties: + id: + type: string + name: + type: string + description: 'The name of the Plugin that’s going to be added. Currently, the Plugin must be installed in every Kong instance separately.' + example: rate-limiting + created_at: + type: integer + description: Unix epoch when the resource was created. + route: + type: string + description: 'If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used. Default: `null`.With form-encoded, the notation is `route.id= or route.name=`. With JSON, use `"route":{"id":""}` or `"route":{"name":""}`.' + nullable: true + service: + type: string + description: 'If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified service.' + nullable: true + consumer: + type: string + description: 'If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.)' + nullable: true + instance_name: + type: string + description: | + The Plugin instance name. + example: rate-limiting-foo + config: + type: object + description: The configuration properties for the Plugin + properties: + hour: + type: integer + example: 500 + minute: + type: integer + example: 500 + protocols: + type: array + description: A list of the request protocols that will trigger this plugin. + items: + type: string + enum: + - http + - grpc + - grpcs + - tls + - tcp + default: http + enabled: + type: boolean + description: | + Whether the plugin is applied. Default: `true`. + default: true + tags: + type: array + description: | + An optional set of strings associated with the Plugin for grouping and filtering. + items: + type: string + ordering: + type: object + description: |- + Describes a dependency to another plugin to determine plugin ordering during the access phase. + –`before`: The plugin will be executed before a specified plugin or list of plugins. + – `after`: The plugin will be executed after a specified plugin or list of plugins. + properties: + before: + type: array + items: + type: string + x-examples: + Example 1: + id: ce44eef5-41ed-47f6-baab-f725cecf98c7 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + instance_name: rate-limiting-foo + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + examples: + Plugin response: + value: + data: + - id: 02621eee-8309-4bf6-b36b-a82017a5393e + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - http + - https + enabled: true + tags: + - user-level + - low-priority + ordering: + before: + - plugin-name + - id: 66c7b5c4-4aaf-4119-af1e-ee3ad75d0af4 + name: rate-limiting + created_at: 1422386534 + route: null + service: null + consumer: null + config: + hour: 500 + minute: 20 + protocols: + - tcp + - tls + enabled: true + tags: + - admin + - high-priority + - critical + ordering: + after: + - plugin-name + next: 'http://localhost:8001/plugins?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + key-set-response: + description: Key set object response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + id: b58c7d9d-e54f-444c-b24d-cdfc4159f61e + name: example-key-set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - idp-keys + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + properties: + id: + type: string + example: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: + type: string + description: | + The name to associate with the given key-set. + example: my-key_set + created_at: + type: integer + description: Unix epoch when the resource was last created. + example: 1422386534 + updated_at: + type: integer + description: |+ + Unix epoch when the resource was last updated. + + example: 1422386534 + tags: + type: array + description: | + The name to associate with the given key-set. + items: + type: string + next: + type: string + description: |+ + Offset is used to paginate through the API. Provide this value to the next list operation to fetch the next page + + example: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + examples: + example: + value: + id: 4D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + name: my-key_set + created_at: 1422386534 + updated_at: 1422386534 + tags: + - string + next: 'http://localhost:8001/key-sets?offset=6378122c-a0a1-438d-a5c6-efabae9fb969' + tags-response: + description: Tags response body + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - entity_name: services + entity_id: acf60b10-125c-4c1a-bffe-6ed55daefba4 + tag: s1 + offset: c47139f3-d780-483d-8a97-17e9adc5a7ab + next: /tags?offset=c47139f3-d780-483d-8a97-17e9adc5a7ab + properties: + data: + type: array + items: + type: object + properties: + entity_name: + type: string + example: services + description: The name of the entity that corresponds to a tag + entity_id: + type: string + example: c87440e1-0496-420b-b06f-dac59544bb6c + description: The unique ID for the entity that is attached to the tag + tag: + type: string + example: example + description: 'The tag ' + offset: + type: string + example: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + next: + type: string + example: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + description: Pagination information + examples: + Tags response: + value: + data: + - entity_name: services + entity_id: c87440e1-0496-420b-b06f-dac59544bb6c + tag: example + offset: 1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 + next: /tags/example?offset=1fb491c4-f4a7-4bca-aeba-7f3bcee4d2f9 +externalDocs: + description: Kong Gateway Admin API (OSS) + url: 'https://docs.konghq.com' +info: + contact: + email: harry@konghq.com + name: Kong Inc + url: 'https://konghq.com' + description: |- + OpenAPI 3.0 spec for Kong Gateway's open source Admin API. + + You can know more about Kong Gateway at [docs.konghq.com](https://docs.konghq.com) + .Give Kong a star at [Kong/kong](https://github.com/kong/kong) repository. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0.html' + title: Kong Admin API + version: 0.0.1 +openapi: 3.0.0 +paths: + /ca_certificates: + get: + description: 'Retrieve a list of all available Certificate Authority (CA) certificates, including the certificate ID, creation date, and other details. You can use query parameters to filter the results by size or tags, for example `/ca-certificates?size=50&tags=enterprise`.' + operationId: list-ca_certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + examples: {} + text/plain: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: A successful response listing CA Certificates + summary: List all CA certificates + tags: + - CA Certificates + post: + description: 'Create a new Certificate Authority (CA) certificate. The request body must include the `cert` property, the certificate data in PEM format; it can also include `cert_digest`, a digest of the certificate in hex format for verifying the certificates integrity, and `tags`, an optional list of tags to categorize the certificate. ' + operationId: create-ca_certificate + responses: + '201': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: The created certificate object. + '400': + description: Invalid CA certificate + summary: Create a new CA certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + '/ca_certificates/{ca_certificate_id}': + delete: + description: Delete the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. + operationId: delete-ca_certificate + responses: + '204': + description: Successfully deleted CA Certificate or the resource didn't exist + summary: Delete a CA Certificate + tags: + - CA Certificates + get: + description: Retrieve details about the specified Certificate Authority (CA) certificate using the provided path parameter `ca_certificate_id`. + operationId: get-ca_certificate + parameters: + - description: The unique identifier of the certificate to retrieve. + in: path + name: ca_certificate_id + required: true + schema: + type: string + examples: + example: + summary: Example CA certificate ID + value: 04fbeacf-a9f1-4a5d-ae4a-b0407445db3f + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: 'The specified CA certificate exists in the system, and the response includes details about the certificate.' + '404': + description: Resource does not exist + summary: Fetch a CA certificate + tags: + - CA Certificates + patch: + description: |- + Update the specified Certificate Authority (CA) certificate using the provided ca_certificate_id. Use this endpoint to modify an existing CA certificate in the system. The request body should include the fields of the CA certificate that need to be updated. + + > This API is not available in DB-less mode. + operationId: update-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully updated CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + '404': + description: Resource does not exist + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + put: + description: Create or Update a CA Certificate using the provided path parameter `ca_certificate_id`. + operationId: updatet-ca_certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CA-Certificate' + description: Successfully upserted CA Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid CA Certificate + summary: Update a CA Certificate + tags: + - CA Certificates + requestBody: + $ref: '#/components/requestBodies/CA-cert-request' + parameters: + - $ref: '#/components/parameters/ca_certificate_id' + /certificates: + get: + description: 'Retrieve a list of all available CA Certificate Authority (CA) certificates. You can use query parameters to filter the results by size or tags, for example `/certificates?size=50&tags=enterprise`.' + operationId: list-certificate + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Certificate' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Certificates + summary: List all certificates + tags: + - Certificates + post: + description: |- + Create a new certificate with the provided details. Use this endpoint to add a new certificate to the system. The request body must include the certificate data and other details required for creating a new certificate. + + > Note: This API is not available in DB-less mode. + operationId: create-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully created Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + summary: Create a new Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + '/certificates/{certificate_id}': + delete: + description: |+ + Delete a Certificate + + >Note: This API is not available in DB-less mode. + + operationId: delete-certificate + parameters: + - description: ID of the Certificate to delete + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Certificate or the resource didn't exist + summary: Delete a Certificate + tags: + - Certificates + get: + description: Retrieve details about the specified certificate using the provided path parameter `certificate_id`. + operationId: get-certificate + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: HTTP 200 OK + '404': + description: Resource does not exist + summary: Fetch a Certificate + tags: + - Certificates + patch: + description: |- + Update a Certificate + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + >Note: This API is not available in DB-less mode. + operationId: update-certificate + parameters: + - description: ID of the Certificate to update + in: path + name: certificate_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully updated Certificate + '400': + description: Invalid Certificate + '404': + description: Resource does not exist + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + put: + description: |+ + Update details about the specified certificate using the provided path parameter `certificate_id`. + + Inserts (or replaces) the certificate under the requested `certificate_id`with the definition specified in the request body. When the `name` or `id` attribute has the structure of a UUID, the certificate being inserted/replaced will be identified by its `id`. Otherwise it will be identified by the `name`. + + When creating a new Certificate without specifying `id` (neither in the path or the request body), then it will be auto-generated. + + + + > Note: This API is not available in DB-less mode. + + operationId: update-certificate-put + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Certificate' + description: Successfully upserted Certificate + '400': + content: + application/json: + schema: + type: object + description: Invalid Certificate + summary: Update a Certificate + tags: + - Certificates + requestBody: + $ref: '#/components/requestBodies/cert-request' + parameters: + - $ref: '#/components/parameters/certificate_id' + '/certificates/{certificate_name_or_id}/snis': + get: + description: Retrieve a paginated list of all SNIs associated with a certificate. Use this endpoint to retrieve a list of SNIs that are linked to a specific certificate. You can use the optional query parameters to filter the results based on specific criteria. The response will include the list of SNIs and pagination information. See the response schema for details on the expected format of the response body. + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + summary: List SNIs associated with a certificate + tags: + - SNIs + operationId: get-sni-with-certificate + post: + description: Create a new SNI and associate it with a certificate in the system. Use this endpoint to add a new SNI to the system and link it to a specific certificate. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully created SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + summary: Create a new SNI associated with a Certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: create-sni-for-certificate + parameters: + - $ref: '#/components/parameters/certificate_name_or_id' + '/certificates/{certificate_id}/snis/{sni_name_or_id}': + delete: + description: | + Delete a an SNI associated with a Certificate using ID or name. + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + summary: Delete a an SNI associated with a Certificate + tags: + - SNIs + operationId: delete-sni-for-certificate + get: + description: Get an SNI associated with a Certificate using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully fetched SNI + '404': + description: Resource does not exist + summary: Fetch an SNI associated with a certificate + tags: + - SNIs + operationId: fetch-sni-with-certificate + patch: + description: |2+ + Update an existing SNI associated with a certificate in the system using the SNI ID or name. The request body should include the fields of the SNI that need to be updated, such as the name, description, or other properties. If the request body contains valid data, the endpoint will update the SNI and return a success response. + + + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully updated SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '404': + description: Resource does not exist + summary: Update SNI associated to a certificate + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + operationId: update-sni-for-certificate + put: + description: | + Create or Update an SNI associated with a Certificate using ID or name. + + Inserts (or replaces) the SNI under the requested resource with the definition specified in the body. The SNI will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the SNI being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new SNI without specifying id (neither in the URL nor in the body), then it will be auto-generated. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SNI' + description: Successfully upserted SNI + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + summary: Upsert an SNI associated with a certificate + tags: + - SNIs + operationId: upsert-sni-for-certificate + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - name: certificate_id + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41" + description: The unique identifier of the Certificate to retrieve. + - name: sni_name_or_id + in: path + required: true + schema: + type: string + example: my-sni + description: The unique identifier or the name of the SNI to retrieve. + /consumers: + get: + description: 'Retrieve a list of all consumers.You can use query parameters to filter the results by size or tags, for example `/consumers?size=50&tags=enterprise`.' + operationId: list-consumer + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Consumer' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Consumers + summary: List all Consumers + tags: + - Consumers + post: + description: Create a new Consumer + operationId: create-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully created Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + summary: Create a new Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + '/consumers/{consumer_username_or_id}': + delete: + description: Delete a specific consumer from the system using either the consumer ID or the consumer username. This operation is irreversible and permanently removes all data associated with the specified consumer. If the consumer was deleted succesfully the endpoint will return a 204 response indicating that the resource did not exist. + operationId: delete-consumer + responses: + '204': + description: Successfully deleted Consumer or the resource didn't exist + summary: Delete a Consumer + tags: + - Consumers + get: + description: 'Retrieve the details of a specific consumer in the system using either the consumer ID or the consumer username. If the consumer with the specified ID or username cannot be found, the endpoint will return a 404.' + operationId: get-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully fetched Consumer + '404': + description: Resource does not exist + summary: Fetch a Consumer + tags: + - Consumers + patch: + description: 'Update the details of a specific consumer in the system using either the consumer ID or the consumer username.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404.' + operationId: update-consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Consumer' + description: Successfully updated Consumer + '400': + content: + application/json: + schema: + type: object + description: Invalid Consumer + '404': + description: Resource does not exist + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + put: + description: |- + Create or Update Consumer using ID or username. The consumer will be identified via the username or id attribute.If the consumer with the specified ID or username cannot be found, the endpoint will return a 404. + + When the username or id attribute has the structure of a UUID, the Consumer being inserted/replaced will be identified by its id. Otherwise it will be identified by its username. + + When creating a new Consumer without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a username in the URL and a different one in the request body is not allowed. + + > Note: This API is not available in DB-less mode. + operationId: upsert-consumer + responses: + '200': + $ref: '#/components/responses/consumer-response-data' + '400': + description: Bad Request + '404': + description: Not Found + summary: Update a Consumer + tags: + - Consumers + requestBody: + $ref: '#/components/requestBodies/consumer-request' + parameters: + - name: consumer_username_or_id + in: path + required: true + schema: + type: string + example: my-username + description: The unique identifier or the username of the Consumer to retrieve. + '/consumers/{consumer_username_or_id}/plugins': + get: + description: 'Retrieve a list of all plugins associated with a consumer. ' + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all plugins associated with a consumer + tags: + - Plugins + operationId: list-plugins-for-consumer + post: + description: Create a new Plugin associated with a Consumer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + '/consumers/{consumer_username_or_id}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a Consumer using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + summary: Delete a Plugin associated with a Consumer + tags: + - Plugins + operationId: delete-plugin-for-consumer + get: + description: Get a Plugin associated with a Consumer using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a Consumer + tags: + - Plugins + operationId: fetch-plugin-for-consumer + patch: + description: Update a Plugin associated with a consumer using the consumer username or ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '404': + description: Resource does not exist + summary: Update a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-consumer + put: + description: Create or Update a Plugin associated with a Consumer using ID. + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: Upsert a Plugin associated with a Consumer + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-consumer + parameters: + - $ref: '#/components/parameters/consumer_username_or_id' + - $ref: '#/components/parameters/plugin_id' + /key-sets: + get: + description: |+ + Retrieve a list of all Key-sets in the system. A Key Set object holds a collection of asymmetric key objects. This entity allows to logically group keys by their purpose. Key Sets can be both tagged and filtered by tags. + + operationId: list-key-set + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/key-set-response' + summary: List all Key-sets + tags: + - Key-sets + post: + description: 'This endpoint allows creating a new Key-set by sending a JSON object that describes the Key-set to be created.The request body must contain all the fields required to create a new Key-set. ' + operationId: create-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + description: ' Returned if the request contains invalid data.' + summary: Create a new Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + '/key-sets/{key-set_id_or_name}': + delete: + description: |- + Delete a Key-set + + > Note: This API is not available in DB-less mode. + operationId: delete-key-set + responses: + '204': + description: Successfully deleted Key-set or the resource didn't exist + summary: Delete a Key-set + tags: + - Key-sets + get: + description: This endpoint retrieves information about a specific key-set based on its ID or name. + operationId: get-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '404': + description: Resource does not exist + summary: Fetch a Key-set + tags: + - Key-sets + patch: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + + Inserts (or replaces) the Key Set under the requested resource with the definition specified in the body. The Key Set will be identified via the name or id attribute. + + When the name or id attribute has the structure of a UUID, the Key Set being inserted/replaced will be identified by its id. Otherwise it will be identified by its name. + + When creating a new Key Set without specifying id (neither in the URL nor in the body), then it will be auto-generated. + + Notice that specifying a name in the URL and a different one in the request body is not allowed. + operationId: update-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + '404': + description: Resource does not exist + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + put: + description: |- + Update a Key-set using ID or name. + + > Note: This API is not available in DB-less mode. + operationId: upsert-key-set + responses: + '200': + $ref: '#/components/responses/key-set-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid Key-set + summary: Update a Key-set + tags: + - Key-sets + requestBody: + $ref: '#/components/requestBodies/key-set-request' + parameters: + - $ref: '#/components/parameters/key-set_id_or_name' + /keys: + get: + description: List all Keys + operationId: list-key + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Key' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Keys + summary: List all Keys + tags: + - Keys + post: + description: |+ + This API endpoint allows you to create a new key. When the request is successful, the API will respond with a 200 status code and a JSON object that represents the newly created key. If the request is invalid, the API will respond with a `400` status code and an error message in the response body. + + > Note: This API is not available in DB-less mode. + + operationId: create-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + description: Successfully created Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + summary: Create a new Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + '/keys/{key_id_or_name}': + delete: + description: Delete a Key + operationId: delete-key + responses: + '204': + description: Successfully deleted Key or the resource didn't exist + summary: Delete a Key + tags: + - Keys + get: + description: Get a Key using ID or name. + operationId: get-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully fetched Key + '404': + description: Resource does not exist + summary: Fetch a Key + tags: + - Keys + patch: + description: Update a Key + operationId: update-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: 24D0DBDA-671C-11ED-BA0B-EF1DCCD3725F + set: + id: 46CA83EE-671C-11ED-BFAB-2FE47512C77A + name: my-key + kid: '42' + jwk: '{"alg":"RSA", "kid": "42", ...}' + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + tags: + - application-a + - public-key-xyz + created_at: 1422386534 + updated_at: 1422386534 + description: Successfully updated Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + '404': + description: Resource does not exist + summary: Update a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + put: + description: Create or Update Key using ID or name. + operationId: upsert-key + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Key' + examples: + Example: + value: + id: d958f66b-8e99-44d2-b0b4-edd5bbf24658 + jwk: '{"alg":"RSA", "kid": "42", ...}' + kid: '42' + name: a-key + pem: + private_key: '-----BEGIN' + public_key: '-----BEGIN' + set: + id: b86b331c-dcd0-4b3e-97ce-47c5a9543031 + description: Successfully upserted Key + '400': + content: + application/json: + schema: + type: object + description: Invalid Key + summary: Upsert a Key + tags: + - Keys + requestBody: + $ref: '#/components/requestBodies/keys-request' + parameters: + - $ref: '#/components/parameters/key_id_or_name' + /plugins: + get: + description: 'This endpoint allows you to list all the plugins. You can use query parameters to filter the results by size or tags, for example `/plugins?size=50&tags=enterprise`.' + operationId: list-plugin + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/plugin-response' + summary: List all Plugins + tags: + - Plugins + post: + description: |- + Create a new Plugin + + >Note: This API is not available in DB-less mode. + operationId: create-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + '/plugins/{plugin_id}': + delete: + description: Delete a Plugin + operationId: delete-plugin + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + summary: Delete a Plugin + tags: + - Plugins + get: + description: Get a Plugin using ID. + operationId: get-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + summary: Fetch a Plugin + tags: + - Plugins + patch: + description: Update a Plugin + operationId: update-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '404': + description: Resource does not exist + summary: Update a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + put: + description: Create or Update Plugin using ID. + operationId: upsert-plugin + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Upsert a Plugin + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + parameters: + - $ref: '#/components/parameters/plugin_id' + /routes: + get: + description: |- + List all routes + + route entities define rules to match client requests. Each route is associated with a service, and a service may have multiple routes associated to it. Every request matching a given route will be proxied to its associated service. + + > Note: Path handling algorithms v1 was deprecated in Kong 3.0. From Kong 3.0, when router_flavor is set to expressions, route.path_handling will be unconfigurable and the path handling behavior will be "v0"; when router_flavor is set to traditional_compatible, the path handling behavior will be "v0" regardless of the value of route.path_handling. Only router_flavor = traditional will support path_handling "v1' behavior. + operationId: list-route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing routes + summary: List all routes + tags: + - Routes + post: + description: Create a new route + operationId: create-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + summary: Create a new route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + '/routes/{route_id_or_name}': + delete: + description: |- + Delete a route + + + > Note: This API is not available in DB-less mode. + operationId: delete-route + responses: + '204': + description: Successfully deleted route or the resource didn't exist + summary: Delete a route + tags: + - Routes + get: + description: Get a route using ID or name. + operationId: get-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully fetched route + '404': + description: Resource does not exist + summary: Fetch a route + tags: + - Routes + patch: + description: |- + Update a route + + > Note: This API is not available in DB-less mode. + operationId: update-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '404': + description: Resource does not exist + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + put: + description: |- + Create or Update route using ID or name. + + + > Note: This API is not available in DB-less mode. + operationId: upsert-route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + summary: Update a route + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + parameters: + - $ref: '#/components/parameters/route_id_or_name' + '/routes/{route_id_or_name}/plugins': + get: + description: List all Plugins associated with a route + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + summary: List all Plugins associated with a route + tags: + - Plugins + operationId: list-plugins-for-route + post: + description: Create a new Plugin associated with a route + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + examples: + example: + value: + config: + anonymous: null + hide_credentials: false + key_in_body: false + key_in_header: true + key_in_query: true + key_names: + - apikey + run_on_preflight: true + enabled: true + id: 3fd1eea1-885a-4011-b986-289943ff8177 + name: key-auth + protocols: + - grpc + - grpcs + - http + - https + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-route + parameters: + - name: route_id_or_name + in: path + required: true + schema: + type: string + example: my-route + description: The unique identifier or the name of the route to retrieve. + '/routes/{route_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a route using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + summary: Delete a Plugin associated with a route + tags: + - Plugins + operationId: delete-plugin-for-route + get: + description: Get a Plugin associated with a route using ID. + parameters: + - description: ID or name of the related route + in: path + name: route_id_or_name + required: true + schema: + type: string + - description: ID of the route to lookup + in: path + name: plugin_id + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a route + tags: + - Plugins + operationId: fetch-plugin-for-route + patch: + description: Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '404': + description: Resource does not exist + summary: Update a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-route + put: + description: Create or Update a Plugin associated with a route using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Upsert a Plugin associated with a route + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-route + parameters: + - $ref: '#/components/parameters/route_id_or_name' + - $ref: '#/components/parameters/plugin_id' + /services: + get: + description: List all services + operationId: list-service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + application/xml: + schema: + type: object + properties: {} + description: A successful response listing services + summary: List all services + tags: + - Services + post: + description: Create a new service + operationId: create-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully created service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + summary: Create a new service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + '/services/{service_id_or_name}': + delete: + description: Delete a service + operationId: delete-service + parameters: + - description: ID or name of the service to delete + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted service or the resource didn't exist + summary: Delete a service + tags: + - Services + get: + description: Get a service using ID or name. + operationId: get-service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully fetched service + '404': + description: Resource does not exist + summary: Fetch a service + tags: + - Services + patch: + description: Update a service + operationId: update-service + parameters: + - description: ID or name of the service to update + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully updated service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + '404': + description: Resource does not exist + summary: Update a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + put: + description: Create or Update service using ID or name. + operationId: upsert-service + parameters: + - description: Name or ID of the service to lookup + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Service' + description: Successfully upserted service + '400': + content: + application/json: + schema: + type: object + description: Invalid service + summary: Upsert a service + tags: + - Services + requestBody: + $ref: '#/components/requestBodies/service-request' + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}plugins': + get: + description: List all Plugins associated with a service + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Plugin' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Plugins + summary: List all Plugins associated with a service + tags: + - Plugins + operationId: get-plugins-for-service + post: + description: Create a new Plugin associated with a service + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully created Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Create a new Plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: create-plugin-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/plugins/{plugin_id}': + delete: + description: Delete a Plugin associated with a service using ID. + responses: + '204': + description: Successfully deleted Plugin or the resource didn't exist + summary: Delete a plugin associated with a service + tags: + - Plugins + operationId: delete-plugin-for-a-service + get: + description: Get a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully fetched Plugin + '404': + description: Resource does not exist + summary: Fetch a Plugin associated with a service + tags: + - Plugins + operationId: fetch-plugin-with-a-service + patch: + description: Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully updated Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + '404': + description: Resource does not exist + summary: Update a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: update-plugin-for-a-service + put: + description: Create or Update a Plugin associated with a service using ID. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Plugin' + description: Successfully upserted Plugin + '400': + content: + application/json: + schema: + type: object + description: Invalid Plugin + summary: Upsert a plugin associated with a service + tags: + - Plugins + requestBody: + $ref: '#/components/requestBodies/plugin-request' + operationId: upsert-plugin-for-a-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/plugin_id' + '/services/{service_id_or_name}/routes': + get: + description: List all routes associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Route' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + Example 1: + value: + data: + - hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + offset: string + description: A successful response listing routes + summary: List all routes associated with a service + tags: + - Routes + operationId: list-routes-for-service + post: + description: Create a new route associated with a service + parameters: + - description: ID or name of the related service + in: path + name: service_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + example: + value: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully created route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + summary: Create a new route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: create-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + '/services/{service_id_or_name}/routes/{route_id_or_name}': + delete: + description: Delete a route associated with a service using ID or name. + responses: + '204': + description: Successfully deleted route or the resource didn't exist + summary: Delete a route associated with a service + tags: + - Routes + operationId: delete-route-for-service + get: + description: Get a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully fetched route + '404': + description: Resource does not exist + summary: Fetch a route associated with a service + tags: + - Routes + operationId: fetch-route-for-service + patch: + description: Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully updated route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + '404': + description: Resource does not exist + summary: Update a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: update-route-for-service + put: + description: Create or Update a route associated with a service using ID or name. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Route' + examples: + Example 1: + value: + hosts: + - foo.example.com + - foo.example.us + id: 56c4566c-14cc-4132-9011-4139fcbbe50a + name: example-route + paths: + - /v1 + - /v2 + service: + id: bd380f99-659d-415e-b0e7-72ea05df3218 + description: Successfully upserted route + '400': + content: + application/json: + schema: + type: object + description: Invalid route + summary: Upsert a route associated with a service + tags: + - Routes + requestBody: + $ref: '#/components/requestBodies/route-request' + operationId: upsert-route-for-service + parameters: + - $ref: '#/components/parameters/service_id_or_name' + - $ref: '#/components/parameters/route_id_or_name' + /snis: + get: + description: List all SNIs + operationId: list-sni + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + $ref: '#/components/responses/sni-response' + summary: List all SNIs + tags: + - SNIs + post: + description: Create a new SNI + operationId: create-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + summary: Create a new SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + '/snis/{sni_name_or_id}': + delete: + description: Delete an SNI + operationId: delete-sni + responses: + '204': + description: Successfully deleted SNI or the resource didn't exist + summary: Delete an SNI + tags: + - SNIs + get: + description: Get an SNI using ID or name. + operationId: get-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '404': + description: Resource does not exist + summary: Fetch an SNI + tags: + - SNIs + patch: + description: Update an SNI + operationId: update-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + '404': + description: Resource does not exist + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + put: + description: Create or Update SNI using ID or name. + operationId: upsert-sni + responses: + '200': + $ref: '#/components/responses/sni-response' + '400': + content: + application/json: + schema: + type: object + description: Invalid SNI + summary: Update an SNI + tags: + - SNIs + requestBody: + $ref: '#/components/requestBodies/create-sni' + parameters: + - $ref: '#/components/parameters/sni_name_or_id' + /upstreams: + get: + description: | + List all registered upstreams. You can filter the results by pagination size, offset, or tags like `/upstreams?size=10&offset=0`. + operationId: list-upstream + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Upstream' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + examples: + example: + value: + data: + - algorithm: round-robin + hash_fallback: none + hash_on: none + hash_on_cookie_path: / + healthchecks: + active: + concurrency: 10 + healthy: + http_statuses: + - 200 + - 302 + interval: 0 + successes: 0 + http_path: / + https_verify_certificate: true + timeout: 1 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + interval: 0 + tcp_failures: 0 + timeouts: 0 + passive: + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + type: http + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 500 + - 503 + tcp_failures: 0 + timeouts: 0 + threshold: 0 + id: 6eed5e9c-5398-4026-9a4c-d48f18a2431e + name: api.example.internal + slots: 10000 + offset: string + description: A successful response listing Upstreams + summary: List all Upstreams + tags: + - Upstreams + post: + description: | + Create a new Upstream + operationId: create-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully created Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + summary: Create a new Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + '/upstreams/{upstream_id_or_name}': + delete: + description: Delete an Upstream + operationId: delete-upstream + responses: + '204': + description: Successfully deleted Upstream or the resource didn't exist + summary: Delete an Upstream + tags: + - Upstreams + get: + description: Get an Upstream using ID or name. + operationId: get-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + description: Successfully fetched Upstream + '404': + description: Resource does not exist + summary: Fetch an Upstream + tags: + - Upstreams + patch: + description: Update an Upstream + operationId: update-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + x-my-header: + - foo + - bar + x-another-header: + - bla + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully updated Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + '404': + description: Resource does not exist + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + put: + description: Create or Update Upstream using ID or name. + operationId: upsert-upstream + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Upstream' + examples: + Example 1: + value: + id: 58c8ccbb-eafb-4566-991f-2ed4f678fa70 + created_at: 1422386534 + name: my-upstream + algorithm: round-robin + hash_on: none + hash_fallback: none + hash_on_cookie_path: / + slots: 10000 + healthchecks: + passive: + type: http + healthy: + http_statuses: + - 200 + - 201 + - 202 + - 203 + - 204 + - 205 + - 206 + - 207 + - 208 + - 226 + - 300 + - 301 + - 302 + - 303 + - 304 + - 305 + - 306 + - 307 + - 308 + successes: 0 + unhealthy: + http_statuses: + - 429 + - 500 + - 503 + timeouts: 0 + http_failures: 0 + tcp_failures: 0 + active: + https_verify_certificate: true + healthy: + http_statuses: + - 200 + - 302 + successes: 0 + interval: 0 + unhealthy: + http_failures: 0 + http_statuses: + - 429 + - 404 + - 500 + - 501 + - 502 + - 503 + - 504 + - 505 + timeouts: 0 + tcp_failures: 0 + interval: 0 + type: http + concurrency: 10 + headers: + type: object + properties: + x-my-header: + type: array + items: + type: string + description: The value(s) of the x-my-header header. + x-another-header: + type: array + items: + type: string + description: The value(s) of the x-another-header header. + timeout: 1 + http_path: / + https_sni: example.com + threshold: 0 + tags: + - user-level + - low-priority + host_header: example.com + client_certificate: + id: ea29aaa3-3b2d-488c-b90c-56df8e0dd8c6 + use_srv_name: false + description: Successfully upserted Upstream + '400': + content: + application/json: + schema: + type: object + description: Invalid Upstream + summary: Update an Upstream + tags: + - Upstreams + requestBody: + $ref: '#/components/requestBodies/upstream-request' + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + '/upstreams/{upstream_id_or_name}/targets': + get: + description: List all Targets associated with a an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Target' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Targets + summary: List all Targets associated with an Upstream + tags: + - Targets + operationId: list-targets-for-upstream + post: + description: Create a new Target associated with an Upstream + parameters: + - description: ID or name of the related Upstream + in: path + name: upstream_id_or_name + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + examples: + Successfully created Target: + value: + id: 173a6cee-90d1-40a7-89cf-0329eca780a6 + created_at: 1422386534 + upstream: + id: bdab0e47-4e37-4f0b-8fd0-87d95cc4addc + target: 'example.com:8000' + weight: 100 + tags: + - user-level + - low-priority + description: Successfully created Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + summary: Create a new Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: create-target-for-upstream + parameters: + - name: upstream_id_or_name + in: path + required: true + schema: + type: string + example: 7fca84d6-7d37-4a74-a7b0-93e576089a41 + description: The unique identifier or the name of the Upstream associated to the Certificate to be retrieved. + '/upstreams/{upstream_id_or_name}/targets/{target_id_or_target}': + delete: + description: Delete a Target associated with a an Upstream using ID or target. + responses: + '204': + description: Successfully deleted Target or the resource didn't exist + summary: Delete a Target associated with a an Upstream + tags: + - Targets + operationId: delete-upstream-target + get: + description: Get a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully fetched Target + '404': + description: Resource does not exist + summary: Fetch a Target associated with an Upstream + tags: + - Targets + operationId: fetch-target-for-upstream + patch: + description: Update a Target associated with a an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully updated Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + '404': + description: Resource does not exist + summary: Update a target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: update-target-for-upstream + put: + description: Create or Update a Target associated with an Upstream using ID or target. + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Target' + description: Successfully upserted Target + '400': + content: + application/json: + schema: + type: object + description: Invalid Target + summary: Upsert a Target associated with an Upstream + tags: + - Targets + requestBody: + $ref: '#/components/requestBodies/target-request' + operationId: upsert-target-for-upstream + parameters: + - $ref: '#/components/parameters/upstream_id_or_name' + - $ref: '#/components/parameters/target_id_or_target' + /vaults: + get: + description: List all Vaults + operationId: list-vault + parameters: + - $ref: '#/components/parameters/pagination-size' + - $ref: '#/components/parameters/pagination-offset' + - $ref: '#/components/parameters/pagination-tags-filter' + responses: + '200': + content: + application/json: + schema: + properties: + data: + items: + $ref: '#/components/schemas/Vault' + type: array + offset: + $ref: '#/components/schemas/pagination-offset-response' + description: A successful response listing Vaults + summary: List all Vaults + tags: + - Vaults + post: + description: Create a new Vault + operationId: create-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully created Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + summary: Create a new Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + '/vaults/{vault_id_or_prefix}': + delete: + description: Delete a Vault + operationId: delete-vault + parameters: + - description: ID or prefix of the Vault to delete + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '204': + description: Successfully deleted Vault or the resource didn't exist + summary: Delete a Vault + tags: + - Vaults + get: + description: |- + Get a Vault using ID or prefix. + + Vault entities are used to configure different Vault connectors. + operationId: get-vault + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully fetched Vault + '404': + description: Resource does not exist + summary: Fetch a Vault + tags: + - Vaults + patch: + description: Update a Vault + operationId: update-vault + parameters: + - description: ID or prefix of the Vault to update + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully updated Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + '404': + description: Resource does not exist + summary: Update a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + put: + description: Create or Update Vault using ID or prefix. + operationId: upsert-vault + parameters: + - description: Name or ID of the Vault to lookup + in: path + name: vault_id_or_prefix + required: true + schema: + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/Vault' + description: Successfully upserted Vault + '400': + content: + application/json: + schema: + type: object + description: Invalid Vault + summary: Upsert a Vault + tags: + - Vaults + requestBody: + $ref: '#/components/requestBodies/vault-request' + parameters: + - $ref: '#/components/parameters/vault_id_or_prefix' + /endpoints: + get: + summary: List all endpoints + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{ceritificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{ceritificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + properties: + data: + type: array + description: An array of all available endpoints. + items: + type: string + examples: + All routes: + value: + data: + - / + - /acls + - '/acls/{acls}' + - '/acls/{acls}/consumer' + - /acme + - /acme/certificates + - '/acme/certificates/{ceritificates}' + - /acme_storage + - '/acme_storage/{acme_storage}' + - /admins + - /admins/password_resets + - /admins/register + - /admins/self/password + - /admins/self/token + - '/admins/{admins}' + - '/admins/{admins}/consumer' + - '/admins/{admins}/rbac_user' + - '/admins/{admin}/roles' + - '/admins/{admin}/workspaces' + - /applications + - '/applications/{applications}' + - '/applications/{applications}/application_instances' + - '/applications/{applications}/application_instances/{application_instances}' + - '/applications/{applications}/consumer' + - '/applications/{applications}/credentials/{plugin}' + - '/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/applications/{applications}/developer' + - /auth + - /basic-auths + - '/basic-auths/{basicauth_credentials}' + - '/basic-auths/{basicauth_credentials}/consumer' + - /ca_certificates + - '/ca_certificates/{ca_certificates}' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - '/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - /cache + - '/cache/{key}' + - /certificates + - '/certificates/{certificates}' + - '/certificates/{certificates}/services' + - '/certificates/{certificates}/services/{services}' + - '/certificates/{certificates}/snis' + - '/certificates/{certificates}/snis/{snis}' + - '/certificates/{certificates}/upstreams' + - '/certificates/{certificates}/upstreams/{upstreams}' + - /clustering/data-planes + - /clustering/status + - /config + - /consumer_groups + - '/consumer_groups/{consumer_groups}' + - '/consumer_groups/{consumer_groups}/consumers' + - '/consumer_groups/{consumer_groups}/consumers/{consumers}' + - '/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - /consumers + - '/consumers/{consumers}' + - '/consumers/{consumers}/acls' + - '/consumers/{consumers}/acls/{acls}' + - '/consumers/{consumers}/admins' + - '/consumers/{consumers}/admins/{admins}' + - '/consumers/{consumers}/applications' + - '/consumers/{consumers}/applications/{applications}' + - '/consumers/{consumers}/basic-auth' + - '/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - '/consumers/{consumers}/consumer_groups' + - '/consumers/{consumers}/consumer_groups/{consumer_groups}' + - '/consumers/{consumers}/developers' + - '/consumers/{consumers}/developers/{developers}' + - '/consumers/{consumers}/hmac-auth' + - '/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - '/consumers/{consumers}/jwt' + - '/consumers/{consumers}/jwt/{jwt_secrets}' + - '/consumers/{consumers}/key-auth' + - '/consumers/{consumers}/key-auth/{keyauth_credentials}' + - '/consumers/{consumers}/key-auth-enc' + - '/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - '/consumers/{consumers}/login_attempts' + - '/consumers/{consumers}/login_attempts/{login_attempts}' + - '/consumers/{consumers}/mtls-auth' + - '/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - '/consumers/{consumers}/mtls_auth_credentials' + - '/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - '/consumers/{consumers}/oauth2' + - '/consumers/{consumers}/oauth2/{oauth2_credentials}' + - '/consumers/{consumers}/plugins' + - '/consumers/{consumers}/plugins/{plugins}' + - '/debug/cluster/log-level/{log_level}' + - /debug/node/log-level + - '/debug/node/log-level/{log_level}' + - /debug/profiling/cpu + - /debug/profiling/gc-snapshot + - /degraphql_routes + - '/degraphql_routes/{degraphql_routes}' + - '/degraphql_routes/{degraphql_routes}/service' + - /developers + - /developers/export + - /developers/invite + - /developers/roles + - '/developers/roles/{rbac_roles}' + - '/developers/{developers}' + - '/developers/{developers}/applications' + - '/developers/{developers}/applications/{applications}' + - '/developers/{developers}/applications/{applications}/application_instances' + - '/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}' + - '/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/consumer' + - '/developers/{developers}/credentials/{plugin}' + - '/developers/{developers}/credentials/{plugin}/{credential_id}' + - '/developers/{developers}/rbac_user' + - '/developers/{email_or_id}/plugins/' + - '/developers/{email_or_id}/plugins/{id}' + - /document_objects + - '/document_objects/{document_objects}' + - '/document_objects/{document_objects}/service' + - /endpoints + - /entities/migrate + - /event-hooks + - /event-hooks/sources + - '/event-hooks/sources/{source}' + - '/event-hooks/sources/{source}/{event}' + - '/event-hooks/{event_hooks}' + - '/event-hooks/{event_hooks}/ping' + - '/event-hooks/{event_hooks}/test' + - /files + - /files/* + - /files/partials/* + - '/files/{files}' + - /graphql-proxy-cache-advanced + - '/graphql-proxy-cache-advanced/{cache_key}' + - '/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /graphql-rate-limiting-advanced/costs + - '/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - /graphql_ratelimiting_advanced_cost_decoration + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - /groups + - '/groups/{groups}' + - '/groups/{groups}/roles' + - /hmac-auths + - '/hmac-auths/{hmacauth_credentials}' + - '/hmac-auths/{hmacauth_credentials}/consumer' + - /jwt-signer/jwks + - '/jwt-signer/jwks/{jwt_signer_jwks}' + - '/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - /jwts + - '/jwts/{jwt_secrets}' + - '/jwts/{jwt_secrets}/consumer' + - /key-auths + - '/key-auths/{keyauth_credentials}' + - '/key-auths/{keyauth_credentials}/consumer' + - /key-auths-enc + - '/key-auths-enc/{keyauth_enc_credentials}' + - '/key-auths-enc/{keyauth_enc_credentials}/consumer' + - /key-sets + - '/key-sets/{key_sets}' + - '/key-sets/{key_sets}/keys' + - '/key-sets/{key_sets}/keys/{keys}' + - /keyring + - /keyring/activate + - /keyring/active + - /keyring/export + - /keyring/generate + - /keyring/import + - /keyring/import/raw + - /keyring/recover + - /keyring/remove + - /keyring/vault/sync + - /keys + - '/keys/{keys}' + - '/keys/{keys}/set' + - /konnect_applications + - '/konnect_applications/{konnect_applications}' + - /license/report + - /licenses + - '/licenses/{licenses}' + - /login_attempts + - '/login_attempts/{login_attempts}' + - '/login_attempts/{login_attempts}/consumer' + - /metrics + - /mtls-auths + - '/mtls-auths/{mtls_auth_credentials}/consumer' + - /mtls_auth_credentials + - '/mtls_auth_credentials/{mtls_auth_credentials}' + - '/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - '/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - /oauth2 + - '/oauth2/{oauth2_credentials}' + - '/oauth2/{oauth2_credentials}/consumer' + - '/oauth2/{oauth2_credentials}/oauth2_tokens' + - '/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - /oauth2_tokens + - '/oauth2_tokens/{oauth2_tokens}' + - '/oauth2_tokens/{oauth2_tokens}/credential' + - '/oauth2_tokens/{oauth2_tokens}/service' + - /openid-connect/issuers + - '/openid-connect/issuers/{oic_issuers}' + - /openid-connect/jwks + - /plugins + - /plugins/enabled + - '/plugins/schema/{name}' + - '/plugins/{plugins}' + - '/plugins/{plugins}/consumer' + - '/plugins/{plugins}/route' + - '/plugins/{plugins}/service' + - /proxy-cache + - '/proxy-cache/{cache_key}' + - '/proxy-cache/{plugin_id}/caches/{cache_key}' + - /proxy-cache-advanced + - '/proxy-cache-advanced/{cache_key}' + - '/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - /rbac/roles + - '/rbac/roles/{rbac_roles}' + - '/rbac/roles/{rbac_roles}/endpoints' + - '/rbac/roles/{rbac_roles}/endpoints/permissions' + - '/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - '/rbac/roles/{rbac_roles}/entities' + - '/rbac/roles/{rbac_roles}/entities/permissions' + - '/rbac/roles/{rbac_roles}/entities/{entity_id}' + - '/rbac/roles/{rbac_roles}/permissions' + - /rbac/users + - '/rbac/users/{rbac_users}' + - '/rbac/users/{rbac_users}/admins' + - '/rbac/users/{rbac_users}/admins/{admins}' + - '/rbac/users/{rbac_users}/developers' + - '/rbac/users/{rbac_users}/developers/{developers}' + - '/rbac/users/{rbac_users}/permissions' + - '/rbac/users/{rbac_users}/roles' + - /routes + - '/routes/{routes}' + - '/routes/{routes}/plugins' + - '/routes/{routes}/plugins/{plugins}' + - '/routes/{routes}/service' + - /schemas/plugins/validate + - '/schemas/plugins/{name}' + - '/schemas/{db_entity_name}/validate' + - '/schemas/{name}' + - /services + - '/services/{services}' + - '/services/{services}/application_instances' + - '/services/{services}/application_instances/{application_instances}' + - '/services/{services}/applications' + - '/services/{services}/client_certificate' + - '/services/{services}/degraphql/routes' + - '/services/{services}/degraphql/routes/{degraphql_routes}' + - '/services/{services}/degraphql_routes' + - '/services/{services}/degraphql_routes/{degraphql_routes}' + - '/services/{services}/document_objects' + - '/services/{services}/document_objects/{document_objects}' + - '/services/{services}/graphql-rate-limiting-advanced/costs' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - '/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - '/services/{services}/oauth2_tokens' + - '/services/{services}/oauth2_tokens/{oauth2_tokens}' + - '/services/{services}/plugins' + - '/services/{services}/plugins/{plugins}' + - '/services/{services}/routes' + - '/services/{services}/routes/{routes}' + - /sessions + - '/sessions/{sessions}' + - /snis + - '/snis/{snis}' + - '/snis/{snis}/certificate' + - /status + - /tags + - '/tags/{tags}' + - /targets + - '/targets/{targets}' + - '/targets/{targets}/upstream' + - /timers + - /upstreams + - '/upstreams/{upstreams}' + - '/upstreams/{upstreams}/client_certificate' + - '/upstreams/{upstreams}/health' + - '/upstreams/{upstreams}/targets' + - '/upstreams/{upstreams}/targets/all' + - '/upstreams/{upstreams}/targets/{targets}' + - '/upstreams/{upstreams}/targets/{targets}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/unhealthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - '/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - /userinfo + - /vault-auth + - '/vault-auth/{vault_auth_vaults}' + - '/vault-auth/{vault}/credentials' + - '/vault-auth/{vault}/credentials/token/{access_token}' + - '/vault-auth/{vault}/credentials/{consumer}' + - /vaults + - '/vaults/{vaults}' + - /vitals/ + - /vitals/cluster + - /vitals/cluster/status_codes + - '/vitals/consumers/{consumer_id}/cluster' + - /vitals/nodes/ + - '/vitals/nodes/{node_id}' + - '/vitals/reports/{entity_type}' + - /vitals/status_code_classes + - /vitals/status_codes/by_consumer + - /vitals/status_codes/by_consumer_and_route + - /vitals/status_codes/by_route + - /vitals/status_codes/by_service + - /workspaces + - '/workspaces/{workspaces}' + - '/workspaces/{workspaces}/meta' + - '/{workspace_name}/kong' + - workspace_/acls + - 'workspace_/acls/{acls}' + - 'workspace_/acls/{acls}/consumer' + - workspace_/acme + - workspace_/acme/certificates + - 'workspace_/acme/certificates/{ceritificates}' + - workspace_/acme_storage + - 'workspace_/acme_storage/{acme_storage}' + - workspace_/admins + - workspace_/admins/password_resets + - workspace_/admins/register + - workspace_/admins/self/password + - workspace_/admins/self/token + - 'workspace_/admins/{admins}' + - 'workspace_/admins/{admins}/consumer' + - 'workspace_/admins/{admins}/rbac_user' + - 'workspace_/admins/{admin}/roles' + - 'workspace_/admins/{admin}/workspaces' + - workspace_/applications + - 'workspace_/applications/{applications}' + - 'workspace_/applications/{applications}/application_instances' + - 'workspace_/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/applications/{applications}/consumer' + - 'workspace_/applications/{applications}/credentials/{plugin}' + - 'workspace_/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/applications/{applications}/developer' + - workspace_/auth + - workspace_/basic-auths + - 'workspace_/basic-auths/{basicauth_credentials}' + - 'workspace_/basic-auths/{basicauth_credentials}/consumer' + - workspace_/ca_certificates + - 'workspace_/ca_certificates/{ca_certificates}' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials' + - 'workspace_/ca_certificates/{ca_certificates}/mtls_auth_credentials/{mtls_auth_credentials}' + - workspace_/cache + - 'workspace_/cache/{key}' + - workspace_/certificates + - 'workspace_/certificates/{certificates}' + - 'workspace_/certificates/{certificates}/services' + - 'workspace_/certificates/{certificates}/services/{services}' + - 'workspace_/certificates/{certificates}/snis' + - 'workspace_/certificates/{certificates}/snis/{snis}' + - 'workspace_/certificates/{certificates}/upstreams' + - 'workspace_/certificates/{certificates}/upstreams/{upstreams}' + - workspace_/clustering/data-planes + - workspace_/clustering/status + - workspace_/config + - workspace_/consumer_groups + - 'workspace_/consumer_groups/{consumer_groups}' + - 'workspace_/consumer_groups/{consumer_groups}/consumers' + - 'workspace_/consumer_groups/{consumer_groups}/consumers/{consumers}' + - 'workspace_/consumer_groups/{consumer_groups}/overrides/plugins/rate-limiting-advanced' + - workspace_/consumers + - 'workspace_/consumers/{consumers}' + - 'workspace_/consumers/{consumers}/acls' + - 'workspace_/consumers/{consumers}/acls/{acls}' + - 'workspace_/consumers/{consumers}/admins' + - 'workspace_/consumers/{consumers}/admins/{admins}' + - 'workspace_/consumers/{consumers}/applications' + - 'workspace_/consumers/{consumers}/applications/{applications}' + - 'workspace_/consumers/{consumers}/basic-auth' + - 'workspace_/consumers/{consumers}/basic-auth/{basicauth_credentials}' + - 'workspace_/consumers/{consumers}/consumer_groups' + - 'workspace_/consumers/{consumers}/consumer_groups/{consumer_groups}' + - 'workspace_/consumers/{consumers}/developers' + - 'workspace_/consumers/{consumers}/developers/{developers}' + - 'workspace_/consumers/{consumers}/hmac-auth' + - 'workspace_/consumers/{consumers}/hmac-auth/{hmacauth_credentials}' + - 'workspace_/consumers/{consumers}/jwt' + - 'workspace_/consumers/{consumers}/jwt/{jwt_secrets}' + - 'workspace_/consumers/{consumers}/key-auth' + - 'workspace_/consumers/{consumers}/key-auth/{keyauth_credentials}' + - 'workspace_/consumers/{consumers}/key-auth-enc' + - 'workspace_/consumers/{consumers}/key-auth-enc/{keyauth_enc_credentials}' + - 'workspace_/consumers/{consumers}/login_attempts' + - 'workspace_/consumers/{consumers}/login_attempts/{login_attempts}' + - 'workspace_/consumers/{consumers}/mtls-auth' + - 'workspace_/consumers/{consumers}/mtls-auth/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials' + - 'workspace_/consumers/{consumers}/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/consumers/{consumers}/oauth2' + - 'workspace_/consumers/{consumers}/oauth2/{oauth2_credentials}' + - 'workspace_/consumers/{consumers}/plugins' + - 'workspace_/consumers/{consumers}/plugins/{plugins}' + - 'workspace_/debug/cluster/log-level/{log_level}' + - workspace_/debug/node/log-level + - 'workspace_/debug/node/log-level/{log_level}' + - workspace_/debug/profiling/cpu + - workspace_/debug/profiling/gc-snapshot + - workspace_/degraphql_routes + - 'workspace_/degraphql_routes/{degraphql_routes}' + - 'workspace_/degraphql_routes/{degraphql_routes}/service' + - workspace_/developers + - workspace_/developers/export + - workspace_/developers/invite + - workspace_/developers/roles + - 'workspace_/developers/roles/{rbac_roles}' + - 'workspace_/developers/{developers}' + - 'workspace_/developers/{developers}/applications' + - 'workspace_/developers/{developers}/applications/{applications}' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances' + - 'workspace_/developers/{developers}/applications/{applications}/application_instances/{application_instances}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}' + - 'workspace_/developers/{developers}/applications/{applications}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/consumer' + - 'workspace_/developers/{developers}/credentials/{plugin}' + - 'workspace_/developers/{developers}/credentials/{plugin}/{credential_id}' + - 'workspace_/developers/{developers}/rbac_user' + - 'workspace_/developers/{email_or_id}/plugins/' + - 'workspace_/developers/{email_or_id}/plugins/{id}' + - workspace_/document_objects + - 'workspace_/document_objects/{document_objects}' + - 'workspace_/document_objects/{document_objects}/service' + - workspace_/endpoints + - workspace_/entities/migrate + - workspace_/event-hooks + - workspace_/event-hooks/sources + - 'workspace_/event-hooks/sources/{source}' + - 'workspace_/event-hooks/sources/{source}/{event}' + - 'workspace_/event-hooks/{event_hooks}' + - 'workspace_/event-hooks/{event_hooks}/ping' + - 'workspace_/event-hooks/{event_hooks}/test' + - workspace_/files + - workspace_/files/* + - workspace_/files/partials/* + - 'workspace_/files/{files}' + - workspace_/graphql-proxy-cache-advanced + - 'workspace_/graphql-proxy-cache-advanced/{cache_key}' + - 'workspace_/graphql-proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/graphql-rate-limiting-advanced/costs + - 'workspace_/graphql-rate-limiting-advanced/costs/{graphql_ratelimiting_advanced_cost_decoration}' + - workspace_/graphql_ratelimiting_advanced_cost_decoration + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}/service' + - workspace_/groups + - 'workspace_/groups/{groups}' + - 'workspace_/groups/{groups}/roles' + - workspace_/hmac-auths + - 'workspace_/hmac-auths/{hmacauth_credentials}' + - 'workspace_/hmac-auths/{hmacauth_credentials}/consumer' + - workspace_/jwt-signer/jwks + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}' + - 'workspace_/jwt-signer/jwks/{jwt_signer_jwks}/rotate' + - workspace_/jwts + - 'workspace_/jwts/{jwt_secrets}' + - 'workspace_/jwts/{jwt_secrets}/consumer' + - workspace_/key-auths + - 'workspace_/key-auths/{keyauth_credentials}' + - 'workspace_/key-auths/{keyauth_credentials}/consumer' + - workspace_/key-auths-enc + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}' + - 'workspace_/key-auths-enc/{keyauth_enc_credentials}/consumer' + - workspace_/key-sets + - 'workspace_/key-sets/{key_sets}' + - 'workspace_/key-sets/{key_sets}/keys' + - 'workspace_/key-sets/{key_sets}/keys/{keys}' + - workspace_/keyring + - workspace_/keyring/activate + - workspace_/keyring/active + - workspace_/keyring/export + - workspace_/keyring/generate + - workspace_/keyring/import + - workspace_/keyring/import/raw + - workspace_/keyring/recover + - workspace_/keyring/remove + - workspace_/keyring/vault/sync + - workspace_/keys + - 'workspace_/keys/{keys}' + - 'workspace_/keys/{keys}/set' + - workspace_/konnect_applications + - 'workspace_/konnect_applications/{konnect_applications}' + - workspace_/license/report + - workspace_/licenses + - 'workspace_/licenses/{licenses}' + - workspace_/login_attempts + - 'workspace_/login_attempts/{login_attempts}' + - 'workspace_/login_attempts/{login_attempts}/consumer' + - workspace_/metrics + - workspace_/mtls-auths + - 'workspace_/mtls-auths/{mtls_auth_credentials}/consumer' + - workspace_/mtls_auth_credentials + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/ca_certificate' + - 'workspace_/mtls_auth_credentials/{mtls_auth_credentials}/consumer' + - workspace_/oauth2 + - 'workspace_/oauth2/{oauth2_credentials}' + - 'workspace_/oauth2/{oauth2_credentials}/consumer' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens' + - 'workspace_/oauth2/{oauth2_credentials}/oauth2_tokens/{oauth2_tokens}' + - workspace_/oauth2_tokens + - 'workspace_/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/credential' + - 'workspace_/oauth2_tokens/{oauth2_tokens}/service' + - workspace_/openid-connect/issuers + - 'workspace_/openid-connect/issuers/{oic_issuers}' + - workspace_/openid-connect/jwks + - workspace_/plugins + - workspace_/plugins/enabled + - 'workspace_/plugins/schema/{name}' + - 'workspace_/plugins/{plugins}' + - 'workspace_/plugins/{plugins}/consumer' + - 'workspace_/plugins/{plugins}/route' + - 'workspace_/plugins/{plugins}/service' + - workspace_/proxy-cache + - 'workspace_/proxy-cache/{cache_key}' + - 'workspace_/proxy-cache/{plugin_id}/caches/{cache_key}' + - workspace_/proxy-cache-advanced + - 'workspace_/proxy-cache-advanced/{cache_key}' + - 'workspace_/proxy-cache-advanced/{plugin_id}/caches/{cache_key}' + - workspace_/rbac/roles + - 'workspace_/rbac/roles/{rbac_roles}' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/endpoints/{workspace}/*' + - 'workspace_/rbac/roles/{rbac_roles}/entities' + - 'workspace_/rbac/roles/{rbac_roles}/entities/permissions' + - 'workspace_/rbac/roles/{rbac_roles}/entities/{entity_id}' + - 'workspace_/rbac/roles/{rbac_roles}/permissions' + - workspace_/rbac/users + - 'workspace_/rbac/users/{rbac_users}' + - 'workspace_/rbac/users/{rbac_users}/admins' + - 'workspace_/rbac/users/{rbac_users}/admins/{admins}' + - 'workspace_/rbac/users/{rbac_users}/developers' + - 'workspace_/rbac/users/{rbac_users}/developers/{developers}' + - 'workspace_/rbac/users/{rbac_users}/permissions' + - 'workspace_/rbac/users/{rbac_users}/roles' + - workspace_/routes + - 'workspace_/routes/{routes}' + - 'workspace_/routes/{routes}/plugins' + - 'workspace_/routes/{routes}/plugins/{plugins}' + - 'workspace_/routes/{routes}/service' + - workspace_/schemas/plugins/validate + - 'workspace_/schemas/plugins/{name}' + - 'workspace_/schemas/{db_entity_name}/validate' + - 'workspace_/schemas/{name}' + - workspace_/services + - 'workspace_/services/{services}' + - 'workspace_/services/{services}/application_instances' + - 'workspace_/services/{services}/application_instances/{application_instances}' + - 'workspace_/services/{services}/applications' + - 'workspace_/services/{services}/client_certificate' + - 'workspace_/services/{services}/degraphql/routes' + - 'workspace_/services/{services}/degraphql/routes/{degraphql_routes}' + - 'workspace_/services/{services}/degraphql_routes' + - 'workspace_/services/{services}/degraphql_routes/{degraphql_routes}' + - 'workspace_/services/{services}/document_objects' + - 'workspace_/services/{services}/document_objects/{document_objects}' + - 'workspace_/services/{services}/graphql-rate-limiting-advanced/costs' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration' + - 'workspace_/services/{services}/graphql_ratelimiting_advanced_cost_decoration/{graphql_ratelimiting_advanced_cost_decoration}' + - 'workspace_/services/{services}/oauth2_tokens' + - 'workspace_/services/{services}/oauth2_tokens/{oauth2_tokens}' + - 'workspace_/services/{services}/plugins' + - 'workspace_/services/{services}/plugins/{plugins}' + - 'workspace_/services/{services}/routes' + - 'workspace_/services/{services}/routes/{routes}' + - workspace_/sessions + - 'workspace_/sessions/{sessions}' + - workspace_/snis + - 'workspace_/snis/{snis}' + - 'workspace_/snis/{snis}/certificate' + - workspace_/status + - workspace_/tags + - 'workspace_/tags/{tags}' + - workspace_/targets + - 'workspace_/targets/{targets}' + - 'workspace_/targets/{targets}/upstream' + - workspace_/timers + - workspace_/upstreams + - 'workspace_/upstreams/{upstreams}' + - 'workspace_/upstreams/{upstreams}/client_certificate' + - 'workspace_/upstreams/{upstreams}/health' + - 'workspace_/upstreams/{upstreams}/targets' + - 'workspace_/upstreams/{upstreams}/targets/all' + - 'workspace_/upstreams/{upstreams}/targets/{targets}' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/unhealthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/healthy' + - 'workspace_/upstreams/{upstreams}/targets/{targets}/{address}/unhealthy' + - workspace_/userinfo + - workspace_/vault-auth + - 'workspace_/vault-auth/{vault_auth_vaults}' + - 'workspace_/vault-auth/{vault}/credentials' + - 'workspace_/vault-auth/{vault}/credentials/token/{access_token}' + - 'workspace_/vault-auth/{vault}/credentials/{consumer}' + - workspace_/vaults + - 'workspace_/vaults/{vaults}' + - workspace_/vitals/ + - workspace_/vitals/cluster + - workspace_/vitals/cluster/status_codes + - 'workspace_/vitals/consumers/{consumer_id}/cluster' + - workspace_/vitals/nodes/ + - 'workspace_/vitals/nodes/{node_id}' + - 'workspace_/vitals/reports/{entity_type}' + - workspace_/vitals/status_code_classes + - workspace_/vitals/status_codes/by_consumer + - workspace_/vitals/status_codes/by_consumer_and_route + - workspace_/vitals/status_codes/by_route + - workspace_/vitals/status_codes/by_service + - workspace_/workspaces + - 'workspace_/workspaces/{workspaces}' + - 'workspace_/workspaces/{workspaces}/meta' + operationId: get-endpoints + description: List all available endpoints provided by the Admin API. + parameters: [] + '/{endpoint}': + parameters: + - schema: + type: string + example: key + name: endpoint + in: path + required: true + description: Any available endpoint + head: + summary: Check endpoint or entity existence + operationId: head-endpoints + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:38:29 GMT' + Content-Type: + description: The media type of the message content + schema: + type: string + example: text/html; charset=UTF-8 + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + X-Kong-Admin-Request-ID: + description: 'A unique identifier for the request, generated by Kong' + schema: + type: string + example: aqETeVmkeiGnAMzdUT2JRWroB2myY1lB + X-Kong-Admin-Latency: + description: 'The time taken to process the request on the server, in milliseconds' + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '404': + description: Endpoint does not exist + headers: {} + description: | + Similar to `HTTP` GET, but does not return the body. Returns HTTP 200 when the endpoint exits or HTTP 404 when it does not. Other status codes are possible. + tags: + - Information + options: + summary: List method by endpoint + operationId: options-endpoint + responses: + '204': + description: No Content + headers: + Date: + description: The date and time at which the message was originated + schema: + type: string + example: 'Fri, 14 Apr 2023 17:24:17 GMT' + Connection: + description: Indicates whether the connection will be closed after the message is completed + schema: + type: string + enum: + - keep-alive + - close + example: keep-alive + Access-Control-Allow-Origin: + description: Indicates whether the resource can be accessed by any origin + schema: + type: string + example: '*' + Access-Control-Allow-Headers: + description: Used in response to a preflight request to indicate which HTTP headers can be used during the actual request + schema: + type: string + example: 'Content-Type, Kong-Admin-Token, Kong-Request-Type, Cache-Control' + X-Kong-Admin-Request-ID: + description: 'A unique identifier for the request, generated by Kong' + schema: + type: string + example: gDP1cF3OsNbrgcKPhRNE0RXRNfS7NcoG + Allow: + description: Lists the HTTP methods that are supported for the resource + schema: + type: string + example: 'OPTIONS, PATCH, POST' + Access-Control-Allow-Methods: + description: Indicates the methods allowed when accessing the resource in response to a preflight request + schema: + type: string + example: 'OPTIONS, PATCH, POST' + X-Kong-Admin-Latency: + description: 'The time taken to process the request on the server, in milliseconds' + schema: + type: integer + example: 5 + Server: + description: The software used by the origin server to handle the request + schema: + type: string + example: kong/3.2.2.0-enterprise-edition + '400': + description: Bad Request + description: |+ + List all the supported HTTP methods by an endpoint. This can also be used with a CORS preflight request. + + tags: + - Information + '/schemas/{entity}/validate': + parameters: + - schema: + type: string + name: entity + in: path + required: true + get: + summary: Retrieve entity schema + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + fields: + - id: + auto: true + type: string + uuid: true + properties: + fields: + type: array + description: A value of a schema + items: + type: object + properties: + id: + type: object + description: A value of a schema + properties: + auto: + type: boolean + description: A value of a schema + type: + type: string + description: A value of a schema + uuid: + type: boolean + description: A value of a schema + examples: + A mock schema: + value: + fields: + - id: + auto: true + type: string + uuid: true + - created_at: + auto: true + timestamp: true + type: integer + operationId: get-schemas-entity + description: 'Retrieve the schema of an entity. This is useful to understand what fields an entity accepts, and can be used for building third-party integrations with Kong.' + post: + summary: Validate a configuration against a schema + operationId: post-schemas-entity-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + Message: + type: string + example: schema validation successful + description: A success message + examples: + schema validation successful: + value: + Message: schema validation successful + description: |- + Check validity of a configuration against its entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store. + tags: + - Information + '/schemas/plugins/{plugin_name}': + parameters: + - schema: + type: string + example: basic-auth + name: plugin_name + in: path + required: true + description: The name of a Kong plugin + get: + summary: Retrieve Plugin Schema + tags: + - Information + responses: + '200': + description: OK + operationId: get-schemas-plugins-plugin_name + description: |+ + Retrieve the schema of a plugin’s configuration. This is useful to understand what fields a plugin accepts, and can be used for building third-party integrations to the Kong’s plugin system. + + /schemas/plugins/validate: + post: + summary: Validate plugin schema + operationId: post-schemas-plugins-validate + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: schema validation successful + properties: + message: + type: string + description: A successful message + example: schema validation successful + examples: + schema validation successful: + value: + message: schema validation successful + description: |- + Check validity of a plugin configuration against the plugins entity schema. This allows you to test your input before submitting a request to the entity endpoints of the Admin API. + + + This only performs the schema validation checks, checking that the input configuration is well-formed. A requests to the entity endpoint using the given configuration may still fail due to other reasons, such as invalid foreign key relationships or uniqueness check failures against the contents of the data store + tags: + - Information + /timers: + get: + summary: Retrieve Runtime Debugging Info of Kong’s Timers + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + stats: + sys: + total: 13 + waiting: 12 + runs: 6771 + pending: 0 + running: 1 + flamegraph: + pending: '' + running: '' + elapsed_time: '' + timers: + router-rebuild: + is_running: false + name: router-rebuild + stats: + runs: 464 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 464 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off': + is_running: false + name: 'unix_timestamp=1681492692484.000000;counter=7:meta=debug off' + stats: + runs: 3 + elapsed_time: + avg: 0 + min: 9999999 + max: -1 + variance: 0 + finish: 3 + last_err_msg: '' + meta: + callstack: debug off + name: debug off + worker: + id: 0 + count: 5 + properties: + stats: + type: object + description: Statistics about the worker + properties: + sys: + type: object + description: List of the number of different type of timers + properties: + total: + description: The total number of timers (running + pending + waiting) + type: integer + default: 7 + example: 7 + waiting: + description: The number of unexpired timers + type: integer + default: 7 + example: 7 + runs: + description: The total number of runs for the timers + type: integer + default: 7 + example: 7 + pending: + description: The number of pending timers + type: integer + default: 0 + example: 0 + running: + description: The number of running timers + type: integer + default: 0 + example: 0 + flamegraph: + type: object + description: String-encoded timer-related flamegraph data + properties: + pending: + description: The number of pending timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + running: + description: The number of running timers for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 0 + elapsed_time: + description: The elapsed time for the flamegraph + type: string + example: | + @./kong/init.lua:706:init_worker();@./kong/runloop/handler.lua:1086:before() 17 + timers: + description: Timer statistics for the worker + type: object + properties: + meta: + description: Program callstack of created timers + type: object + properties: + name: + description: The name of the timer's metadata + type: string + example: '@/build/luarocks/share/lua/5.1/resty/counter.lua:71:new()' + worker: + type: object + properties: + id: + type: integer + description: The ordinal number of the current Nginx worker processes (starting from number 0). + count: + type: integer + description: The total number of the Nginx worker processes. + operationId: get-timers + description: 'Retrieve runtime stats data from [lua-resty-timer-ng](https://github.com/Kong/lua-resty-timer-ng).' + /status: + get: + summary: Health Routes + tags: + - Information + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + properties: + memory: + type: object + description: Metrics about the memory usage. + properties: + lua_shared_dicts: + type: object + description: 'An array of information about dictionaries that are shared with all workers in a Kong node, where each array node contains how much memory is dedicated for the specific shared dictionary (capacity) and how much of said memory is in use (allocated_slabs).' + properties: + kong_core_db_cache: + type: object + properties: + capacity: + type: string + example: 128.00 MiB + description: Memory capacity + allocated_slabs: + type: string + example: 128.00 MiB + description: Total allocated memory + workers_lua_vms: + type: array + description: 'An array with all workers of the Kong node, where each entry contains:' + items: + type: object + properties: + http_allocated_gc: + type: string + description: 'HTTP submodule’s Lua virtual machine’s memory usage information, as reported by' + pid: + type: integer + description: worker’s process identification number. + example: 18478 + database: + type: object + description: Metrics about the database + properties: + reachable: + type: boolean + description: A boolean value reflecting the state of the database connection. Please note that this flag does not reflect the health of the database itself. + server: + type: object + description: Metrics about the nginx HTTP/S server + properties: + connections_reading: + type: integer + description: The current number of connections where Kong is reading the request header. + example: 3 + connections_writing: + type: integer + description: The current number of connections where nginx is writing the response back to the client. + example: 1 + total_requests: + type: integer + description: The total number of client requests. + example: 1 + connections_waiting: + type: integer + description: The current number of idle client connections waiting for a request. + example: 1 + connections_handled: + type: integer + description: 'The total number of handled connections. Generally, the parameter value is the same as accepts unless some resource limits have been reached.' + example: 1 + connections_active: + type: integer + description: The current number of active client connections including Waiting connections. + example: 1 + connections_accepted: + type: integer + description: The total number of accepted client connections. + example: 1 + examples: + Status endpoint response: + value: + memory: + lua_shared_dicts: + kong_core_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.76 MiB + kong_core_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_db_cache: + capacity: 128.00 MiB + allocated_slabs: 0.78 MiB + kong_db_cache_miss: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + kong_vitals_counters: + capacity: 50.00 MiB + allocated_slabs: 0.30 MiB + kong_vitals_lists: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_vitals: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_counters: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_consumers: + capacity: 10.00 MiB + allocated_slabs: 0.07 MiB + kong_reports_routes: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_services: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_reports_workspaces: + capacity: 1.00 MiB + allocated_slabs: 0.02 MiB + kong_keyring: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_profiling_state: + capacity: 1.50 MiB + allocated_slabs: 0.02 MiB + prometheus_metrics: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_locks: + capacity: 8.00 MiB + allocated_slabs: 0.06 MiB + kong_healthchecks: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_process_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_cluster_events: + capacity: 5.00 MiB + allocated_slabs: 0.04 MiB + kong_rate_limiting_counters: + capacity: 12.00 MiB + allocated_slabs: 0.08 MiB + workers_lua_vms: + - http_allocated_gc: 51.92 MiB + pid: 2323 + - http_allocated_gc: 51.48 MiB + pid: 2324 + - http_allocated_gc: 51.48 MiB + pid: 2325 + - http_allocated_gc: 51.48 MiB + pid: 2326 + - http_allocated_gc: 51.48 MiB + pid: 2327 + database: + reachable: true + server: + connections_reading: 0 + connections_writing: 6 + total_requests: 28 + connections_waiting: 0 + connections_handled: 15 + connections_active: 6 + connections_accepted: 15 + operationId: get-status + description: |- + Retrieve usage information about a node, with some basic information about the connections being processed by the underlying nginx process, the status of the database connection, and node’s memory usage. + + If you want to monitor the Kong process, since Kong is built on top of nginx, every existing nginx monitoring tool or agent can be used. + /tags: + get: + summary: List all tags + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + operationId: get-tags + description: |- + Returns a paginated list of all the tags in the system. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + + If an entity is tagged with more than one tag, the entity_id for that entity will appear more than once in the resulting list. Similarly, if several entities have been tagged with the same tag, the tag will appear in several items of this list. + '/tags/{tags}': + parameters: + - $ref: '#/components/parameters/tag' + get: + summary: List entity by tag + tags: + - Tags + responses: + '200': + $ref: '#/components/responses/tags-response' + operationId: get-tags-tags + description: |- + Returns the entities that have been tagged with the specified tag. + + The list of entities will not be restricted to a single entity type: all the entities tagged with tags will be present on this list. + '/debug/cluster/control-planes-nodes/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Control Plane Nodes + operationId: put-debug-cluster-control-planes-nodes-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: Response message + example: log level changed + examples: + log level changed: + value: + message: log level changed + description: |+ + Change the log level of all Control Plane nodes deployed in Hybrid (CP/DP) cluster. + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + Care must be taken when changing the log level of a node to `debug` in a production environment because the disk could fill up quickly. As soon as the debug logging finishes, revert back to a higher level such as notice. + + It’s currently not possible to change the log level of DP and DB-less nodes. + + tags: + - Debug + '/debug/cluster/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set Node Log Level of All Nodes + operationId: put-debug-cluster-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + example: log level changed + description: A message containing information about the log level + examples: + log level changed: + value: + message: log level changed + description: |+ + Change the log level of all nodes in a cluster. + + + + See the [NGINX docs](http://nginx.org/en/docs/ngx_core_module.html#error_log) for a list of accepted values. + + It’s currently not possible to change the log level of DP and DB-less nodes. + + Currently, when a user dynamically changes the log level for the entire cluster, if a new node joins a cluster the new node will run at the previous log level, not at the log level that was previously set dynamically for the entire cluster. + + + tags: + - Debug + /debug/node/log-level: + get: + summary: Retrieve Node Log Level of A Node + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: 'log level: debug' + properties: + message: + type: string + example: 'log level: debug' + description: A message containing the current log level of the node. + examples: + Example 1: + value: + message: 'log level: debug' + operationId: get-debug-node-log-level + description: |- + Retrieve the current log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug + parameters: [] + '/debug/node/log-level/{log_level}': + parameters: + - $ref: '#/components/parameters/log_level' + put: + summary: Set log level of a single node + operationId: put-debug-node-log-level-log_level + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + x-examples: + Example 1: + message: log level changed + properties: + message: + type: string + description: A message confirming the log level change + example: log level changed + examples: + log level changed: + value: + message: log level changed + description: | + Change the log level of a node. + + See the [NGINX documentation](http://nginx.org/en/docs/ngx_core_module.html#error_log) for the list of possible return values. + tags: + - Debug +servers: + - description: Default Admin API URL + url: '{protocol}://{hostname}:{port}{path}' + variables: + hostname: + default: localhost + description: Hostname for Kong's Admin API + path: + default: / + description: Base path for Kong's Admin API + port: + default: '8001' + description: Port for Kong's Admin API + protocol: + default: http + description: Protocol for requests to Kong's Admin API + enum: + - http + - https +tags: + - description: Gateway services + name: Services + - description: Gateway routes + name: Routes + - description: Plugins + name: Plugins + - description: Consumers + name: Consumers + - description: Certificates + name: Certificates + - description: SNIs + name: SNIs + - description: CA certificates + name: CA Certificates + - description: Upstreams + name: Upstreams + - description: Vaults + name: Vaults + - description: Keys + name: Keys + - description: Key-sets + name: Key-sets + - description: Information routes + name: Information + - description: Debug routes + name: Debug + - description: Target routes + name: Targets + - description: Tag rotues + name: Tags diff --git a/app/_data/docs_nav_gateway_3.4.x.yml b/app/_data/docs_nav_gateway_3.4.x.yml index 7f74b5f2ef9e..ab706f229dc9 100644 --- a/app/_data/docs_nav_gateway_3.4.x.yml +++ b/app/_data/docs_nav_gateway_3.4.x.yml @@ -477,6 +477,8 @@ items: url: /plugin-development/pdk/kong.nginx - text: kong.node url: /plugin-development/pdk/kong.node + - text: kong.plugin + url: /plugin-development/pdk/kong.plugin - text: kong.request url: /plugin-development/pdk/kong.request - text: kong.response diff --git a/app/_src/gateway/plugin-development/pdk/index.md b/app/_src/gateway/plugin-development/pdk/index.md index 8e216786c600..fc49ecf768ab 100644 --- a/app/_src/gateway/plugin-development/pdk/index.md +++ b/app/_src/gateway/plugin-development/pdk/index.md @@ -115,7 +115,7 @@ Instance of Kong's DNS resolver, a client object from the ## kong.worker_events Instance of Kong's IPC module for inter-workers communication from the - [lua-resty-worker-events](https://github.com/Kong/lua-resty-worker-events) + [lua-resty-events](https://github.com/Kong/lua-resty-events) module. **Note:** Usage of this module is currently reserved to the core or to diff --git a/app/_src/gateway/plugin-development/pdk/kong.client.md b/app/_src/gateway/plugin-development/pdk/kong.client.md index f0e140d74e8a..ee3b14c27879 100644 --- a/app/_src/gateway/plugin-development/pdk/kong.client.md +++ b/app/_src/gateway/plugin-development/pdk/kong.client.md @@ -10,7 +10,7 @@ pdk: true toc: true source_url: https://github.com/Kong/kong/tree/master/kong/pdk --- - + Client information module. A set of functions to retrieve information about the client connecting to @@ -237,10 +237,21 @@ end ## kong.client.authenticate(consumer, credential) +{% if_version gte:3.4.x %} +Sets the authenticated consumer and/or credential as well + as the authenticated consumer-group for the current request. + While both `consumer` and `credential` can be `nil`, + at least one of them must exist. Otherwise, this function will throw an + error. +{% endif_version %} + +{% if_version lte:3.3.x %} Sets the authenticated consumer and/or credential for the current request. + While both `consumer` and `credential` can be `nil`, at least one of them must exist. Otherwise, this function will throw an error. +{% endif_version %} **Phases** @@ -259,8 +270,30 @@ Sets the authenticated consumer and/or credential for the current request. -- assuming `credential` and `consumer` have been set by some authentication code kong.client.authenticate(consumer, credentials) ``` +{% if_version gte:3.4.x %} + + +## _CLIENT.get_consumer_group() + +Retrieves the authenticated consumer group for the current request. + +**Phases** + +* auth_and_later + +**Returns** + +* `table|nil`: The authenticated consumer group. Returns `nil` if no + consumer group has been authenticated for the current request. +**Usage** + +``` lua +local group = _CLIENT.get_consumer_group() +``` +{% endif_version %} + ## kong.client.get_protocol([allow_terminated]) diff --git a/app/_src/gateway/plugin-development/pdk/kong.plugin.md b/app/_src/gateway/plugin-development/pdk/kong.plugin.md new file mode 100644 index 000000000000..612cf631801e --- /dev/null +++ b/app/_src/gateway/plugin-development/pdk/kong.plugin.md @@ -0,0 +1,37 @@ +--- +# +# WARNING: this file was auto-generated by a script. +# DO NOT edit this file directly. Instead, send a pull request to change +# https://github.com/Kong/kong/tree/master/autodoc/pdk/ldoc/ldoc.ltp +# or its associated files +# +title: kong.plugin +pdk: true +toc: true +source_url: https://github.com/Kong/kong/tree/master/kong/pdk +--- + + + + + +## kong.plugin.get_id() + +Returns the instance ID of the plugin. + +**Phases** + +* rewrite, access, header_filter, response, body_filter, log + +**Returns** + +* `string`: The ID of the running plugin + + +**Usage** + +``` lua +kong.request.get_id() -- "123e4567-e89b-12d3-a456-426614174000" +``` + + diff --git a/app/_src/gateway/plugin-development/pdk/kong.request.md b/app/_src/gateway/plugin-development/pdk/kong.request.md index 378859de82ef..9815f2b072b2 100644 --- a/app/_src/gateway/plugin-development/pdk/kong.request.md +++ b/app/_src/gateway/plugin-development/pdk/kong.request.md @@ -691,8 +691,7 @@ Returns the request data as a key/value table. body could not be parsed. The optional argument `max_args` can be used to set a limit on the number - of form arguments parsed for `application/x-www-form-urlencoded` payloads, - which is by default **100** (or what has been configured using `lua_max_post_args`). + of form arguments parsed for `application/x-www-form-urlencoded` payloads, which is by default **100** (or what has been configured using `lua_max_post_args`). The third return value is string containing the mimetype used to parsed the body (as per the `mimetype` argument), allowing the caller to identify diff --git a/app/_src/gateway/plugin-development/pdk/kong.service.md b/app/_src/gateway/plugin-development/pdk/kong.service.md index 3ae33c64b7ab..29d676b0e8f9 100644 --- a/app/_src/gateway/plugin-development/pdk/kong.service.md +++ b/app/_src/gateway/plugin-development/pdk/kong.service.md @@ -152,7 +152,13 @@ Sets whether TLS verification is enabled while handshaking with the Service. **Phases** +{% if_version lte:3.3.x %} * `rewrite`, `access`, `balancer` +{% endif_version %} + +{% if_version gte:3.4.x %} +* `rewrite`, `access`, `balancer`, `preread` +{% endif_version %} **Parameters** diff --git a/app/_src/gateway/plugin-development/pdk/kong.tracing.md b/app/_src/gateway/plugin-development/pdk/kong.tracing.md index f8d2159cc2b2..041a3f4fd709 100644 --- a/app/_src/gateway/plugin-development/pdk/kong.tracing.md +++ b/app/_src/gateway/plugin-development/pdk/kong.tracing.md @@ -175,4 +175,14 @@ Update the value of should_sample for all spans * **should_sample** (`bool`): value for the sample parameter +{% endif_version %} + +{% if_version gte:3.4.x %} +## kong.tracing:set_should_sample(should_sample) + +Update the value of should_sample for all spans + +**Parameters** + +* **should_sample** (`bool`): value for the sample parameter {% endif_version %} \ No newline at end of file diff --git a/app/_src/gateway/plugin-development/pdk/kong.vault.md b/app/_src/gateway/plugin-development/pdk/kong.vault.md index 4e962cc0bce6..2c7eb84593ae 100644 --- a/app/_src/gateway/plugin-development/pdk/kong.vault.md +++ b/app/_src/gateway/plugin-development/pdk/kong.vault.md @@ -12,6 +12,297 @@ source_url: https://github.com/Kong/kong/tree/master/kong/pdk --- This module can be used to resolve, parse, and verify vault references. +{% if_version gte:3.4.x %} +## get_subfield(value, key) + +This function extracts a subfield from a JSON object. + It first decodes the JSON string into a Lua table, then checks for the presence and type of a specific key. + + +**Parameters** + +* **value** : The JSON string to be parsed and decoded. +* **key** : The specific subfield to be searched for within the JSON object. + +**Returns** + +* On success, returns the value associated with the specified key in the JSON object. + If the key does not exist or its value is not a string, returns nil along with an error message. + If the input value cannot be parsed as a JSON object, also returns nil along with an error message. + + + + +## adjust_ttl(ttl, vault_config) + +This function adjusts the 'time-to-live' (TTL) according to the configuration provided in 'vault_config'. + If the TTL is not a number or if it falls outside of the configured minimum or maximum TTL, it will be adjusted accordingly. + + +**Parameters** + +* **ttl** : The initial time-to-live value. +* **vault_config** : The configuration table for the vault, which may contain 'ttl', 'min_ttl', and 'max_ttl' fields. + +**Returns** + +* Returns the adjusted TTL. If the initial TTL is not a number, it returns the 'ttl' field from the 'vault_config' table or 0 if it doesn't exist. + If the initial TTL is greater than 'max_ttl' from 'vault_config', it returns 'max_ttl'. + If the initial TTL is less than 'min_ttl' from 'vault_config', it returns 'min_ttl'. + Otherwise, it returns the original TTL. + + + + +## get_vault(prefix) + +This function retrieves a vault by its prefix. It either fetches the vault from a cache or directly accesses it. + The vault is expected to be found in a database (db) or cache. If not found, an error message is returned. + + +**Parameters** + +* **prefix** : The unique identifier of the vault to be retrieved. + +**Returns** + +* Returns the vault if it's found. If the vault is not found, it returns nil along with an error message. + + + + +## get_vault_strategy_and_schema_during_init(name) + +Fetches the strategy and schema for a given vault during initialization. + + This function checks if the vault exists in `VAULT_NAMES`, fetches the associated strategy and schema from + the `STRATEGIES` and `SCHEMAS` tables, respectively. If the strategy or schema isn't found in the tables, it + attempts to fetch them from the application's database or by requiring them from a module. + + The fetched strategy and schema are then stored back into the `STRATEGIES` and `SCHEMAS` tables for later use. + If the `init` method exists in the strategy, it's also executed. + + +**Parameters** + +* **name** : string The name of the vault to fetch the strategy and schema for. + +**Returns** + +1. strategy: The fetched or required strategy for the given vault. + +1. schema: The fetched or required schema for the given vault. + +1. `string|nil`: An error message, if an error occurred while fetching or requiring the strategy or schema. + + + + +## parse_and_resolve_reference(reference) + +Function `parse_and_resolve_reference` processes a reference to retrieve configuration settings, + a strategy to be used, and the hash of the reference. + The function first parses the reference. Then, it gets the strategy, the schema, and the base configuration + settings for the vault based on the parsed reference. It checks the license type if required by the strategy. + Finally, it gets the configuration and the hash of the reference. + + +**Parameters** + +* **reference** : The reference to be parsed and resolved. + +**Returns** + +* The configuration, a nil value (as a placeholder for an error that did not occur), + the parsed reference, the strategy to be used, and the hash of the reference. + If an error occurs, it returns `nil` and an error message. + + +**Usage** + +``` lua +local config, _, parsed_reference, strategy, hash = parse_and_resolve_reference(reference) +``` + + + +## get_from_vault(strategy, config, parsed_reference, cache_key, reference) + +Function `get_from_vault` retrieves a value from the vault using the provided strategy. + The function first retrieves a value from the vault and its ttl (time-to-live). + It then adjusts the ttl within configured bounds, stores the value in the SHDICT cache + with a ttl that includes a resurrection time, and stores the value in the LRU cache with + the adjusted ttl. + + +**Parameters** + +* **strategy** : The strategy to be used to retrieve the value from the vault. +* **config** : The configuration settings to be used. +* **parsed_reference** : The parsed reference key to lookup in the vault. +* **cache_key** : The key to be used when storing the value in the cache. +* **reference** : The original reference key. + +**Returns** + +* The retrieved value from the vault. If an error occurs, it returns `nil` and an error message. + + +**Usage** + +``` lua +local value, err = get_from_vault(strategy, config, parsed_reference, cache_key, reference) +``` + + + +## renew_from_vault(reference) + +Function `renew_from_vault` attempts to retrieve a value from the vault. + It first parses and resolves the reference, then uses the resulting strategy, + config, parsed_reference, and cache_key to attempt to get the value from the vault. + + +**Parameters** + +* **reference** : The reference key to lookup in the vault. + +**Returns** + +* The retrieved value from the vault corresponding to the provided reference. + If the value is not found or if an error occurs, it returns `nil` and an error message. + + +**Usage** + +``` lua +local value, err = renew_from_vault(reference) +``` + + + +## get(reference, cache_only) + +Function `get` retrieves a value from local (LRU) or shared dictionary (SHDICT) cache. + If the value is not found in these caches and `cache_only` is not set, it attempts + to retrieve the value from a vault. + + +**Parameters** + +* **reference** : The reference key to lookup in the cache and potentially the vault. +* **cache_only** : Optional boolean flag. If set to true, the function will not attempt + to retrieve the value from the vault if it's not found in the caches. + +**Returns** + +* The retrieved value corresponding to the provided reference. If the value is + not found, it returns `nil` and an error message. + + +**Usage** + +``` lua +local value, err = get(reference, cache_only) +``` + + + +## get_from_cache(references) + +Function `get_from_cache` retrieves values from a cache. + + This function uses the provided references to fetch values from a cache. + The fetching process will return cached values if they exist. + + +**Parameters** + +* **references** : A list or table of reference keys. Each reference key corresponds to a value in the cache. + +**Returns** + +* The retrieved values corresponding to the provided references. If a value does not exist in the cache for a particular reference, it is not clear from the given code what will be returned. + + +**Usage** + +``` lua +local values = get_from_cache(references) +``` + + + +## update(config) + +Function `update` recursively updates a configuration table. + + This function updates a configuration table by replacing reference fields + with values fetched from a cache. The references are specified in a `$refs` + field, which should be a table mapping from field names to reference keys. + + If a reference cannot be fetched from the cache, the corresponding field is + set to an empty string and an error is logged. + + +**Parameters** + +* **config** : A table representing the configuration to update. If `config` + is not a table, the function immediately returns it without any modifications. + +**Returns** + +* The updated configuration table. If the `$refs` field is not a table + or is empty, the function returns `config` as is. + + +**Usage** + +``` lua +local updated_config = update(config) +``` + + + +## try(callback, options) + +Function `try` attempts to execute a provided callback function with the provided options. + If the callback function fails, the `try` function will attempt to resolve references and update + the values in the options table before re-attempting the callback function. + NOTE: This function currently only detects changes by doing a shallow comparison. As a result, it might trigger more retries than necessary - when a config option has a table value and it seems "changed" even if the "new value" is a new table with the same keys and values inside. + +**Parameters** + +* **callback** : The callback function to execute. This function should take an options table as its argument. +* **options** : The options table to provide to the callback function. This table may include a "$refs" field which is a table mapping reference names to their values. + +**Returns** + +* Returns the result of the callback function if it succeeds, otherwise it returns `nil` and an error message. + + + + +## rotate_secrets() + +Function `rotate_secrets` rotates the secrets in the shared dictionary cache (SHDICT). + It iterates over all keys in the SHDICT and, if a key corresponds to a reference and the + ttl of the key is less than or equal to the resurrection period, it refreshes the value + associated with the reference. + + +**Returns** + +* Returns `true` after it has finished iterating over all keys in the SHDICT. + + +**Usage** + +``` lua +local success = rotate_secrets() +``` +{% endif_version %} + {% if_version gte:3.3.x %} ## kong.vault.flush() @@ -116,8 +407,54 @@ Resolves the passed in reference and returns the value of it. ``` lua local value, err = kong.vault.get("{vault://env/cert/key}") ``` +{% if_version gte:3.4.x %} +## kong.vault.update(options) + +Helper function for secret rotation based on TTLs. Currently experimental. + + +**Parameters** + +* **options** (`table`): options containing secrets and references (this function modifies the input options) + +**Returns** + +* `table`: options with updated secret values + + +**Usage** +``` lua +local options = kong.vault.update({ + cert = "-----BEGIN CERTIFICATE-----...", + key = "-----BEGIN RSA PRIVATE KEY-----...", + cert_alt = "-----BEGIN CERTIFICATE-----...", + key_alt = "-----BEGIN EC PRIVATE KEY-----...", + ["$refs"] = { + cert = "{vault://aws/cert}", + key = "{vault://aws/key}", + cert_alt = "{vault://aws/cert-alt}", + key_alt = "{vault://aws/key-alt}", + } +}) +-- or + +local options = { + cert = "-----BEGIN CERTIFICATE-----...", + key = "-----BEGIN RSA PRIVATE KEY-----...", + cert_alt = "-----BEGIN CERTIFICATE-----...", + key_alt = "-----BEGIN EC PRIVATE KEY-----...", + ["$refs"] = { + cert = "{vault://aws/cert}", + key = "{vault://aws/key}", + cert_alt = "{vault://aws/cert-alt}", + key_alt = "{vault://aws/key-alt}", + } +} +kong.vault.update(options) +``` +{% endif_version %} ## kong.vault.try(callback, options) @@ -152,3 +489,36 @@ local connection, err = kong.vault.try(connect, { } }) ``` + +{% if_version gte:3.4.x %} + +## invoke_strategy(strategy, config, parsed_reference) + +Invokes a provided strategy to fetch a secret. + This function invokes a strategy provided to it to retrieve a secret from a resource, with version control. + The secret can have multiple values, each stored under a different key. + The secret returned by the strategy must be a string containing a JSON object, which can be indexed by the key to get a specific value. + If the secret can't be retrieved or doesn't have the expected format, appropriate errors are returned. + + +**Parameters** + +* **strategy** : The strategy used to fetch the secret. +* **config** : The configuration required by the strategy. +* **parsed_reference** : A table containing the resource and version of the secret to be fetched, and optionally, a key to index a specific value. + +**Returns** + +1. Value The value of the secret or subfield if retrieval is successful. + +1. `nil` If retrieval is successful, the second returned value will be nil. + +1. `err` A string describing an error if there was one, or ttl (time to live) of the fetched secret. + + +**Usage** + +``` lua +local value, _, err = invoke_strategy(strategy, config, parsed_reference) +``` +{% endif_version %} \ No newline at end of file