Routes

Upsert a Route

Changed on

Create or Update Route using ID or name.

put/{workspace}/routes/{RouteIdOrName}

Request

  • Base URL: http://localhost:8001
  • URL: http://localhost:8001/{workspace}/routes/{RouteIdOrName}
  • Auth: API key in header Kong-Admin-Token

Path parameters

workspacestring required
Example:team-payments

The name of the workspace

Request body

created_atinteger nullable

Unix epoch when the resource was created.

headersobject nullable

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.

hostsstring[] nullable

A list of domain names that match this Route. Note that the hosts value is case sensitive.

https_redirect_status_code301 | 302 | 307 | 308 | 426 nullable

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.

idstring nullable

A string representing a UUID (universally unique identifier).

methodsstring[] nullable

A list of HTTP methods that match this Route.

namestring nullable

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".

path_handling'v0' | 'v1' nullable

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.

pathsstring[] nullable

A list of paths that match this Route.

preserve_hostboolean nullable

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.

protocolsstring[] nullable

An array of the protocols this Route should allow. See the 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.

regex_priorityinteger nullable

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).

request_bufferingboolean nullable

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.

response_bufferingboolean nullable

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.

snisstring[] nullable

A list of SNIs that match this Route when using stream routing.

strip_pathboolean nullable

When matching a Route via one of the paths, strip the matching prefix from the upstream request URL.

tagsstring[] nullable

An optional set of strings associated with the Route for grouping and filtering.

updated_atinteger nullable

Unix epoch when the resource was last updated.

Example request

{
  "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"
  }
}

Response

Successfully upserted Route

created_atinteger nullable

Unix epoch when the resource was created.

headersobject nullable

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.

hostsstring[] nullable

A list of domain names that match this Route. Note that the hosts value is case sensitive.

https_redirect_status_code301 | 302 | 307 | 308 | 426 nullable

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.

idstring nullable

A string representing a UUID (universally unique identifier).

methodsstring[] nullable

A list of HTTP methods that match this Route.

namestring nullable

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".

path_handling'v0' | 'v1' nullable

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.

pathsstring[] nullable

A list of paths that match this Route.

preserve_hostboolean nullable

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.

protocolsstring[] nullable

An array of the protocols this Route should allow. See the 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.

regex_priorityinteger nullable

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).

request_bufferingboolean nullable

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.

response_bufferingboolean nullable

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.

snisstring[] nullable

A list of SNIs that match this Route when using stream routing.

strip_pathboolean nullable

When matching a Route via one of the paths, strip the matching prefix from the upstream request URL.

tagsstring[] nullable

An optional set of strings associated with the Route for grouping and filtering.

updated_atinteger nullable

Unix epoch when the resource was last updated.

Example response

{
  "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"
  }
}

Changes

  • 9555cbb8b259Revision changes
    • info

      the request property default value changed from http https to https

    • info

      the response's property default value changed from http https to https for the status

  • 740b73588ef4Revision changes
    • info

      endpoint added