Create Or Update Route Associated to a Specific Service
PUT {{gateway}}/services/:serviceNameOrId/routes/:routeNameOrId
Create Or Update Route Associated to a Specific Service konghq
- Inserts (or replaces) the Route under the requested resource with the definition specified in the body. The Route will be identified via the name or id attribute.
- When the name or id attribute has the structure of a UUID, the Route being inserted/replaced will be identified by its id. Otherwise it will be identified by its name.
- When creating a new Route 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.
| Attributes | Mandatory | Type | Description |
|---|---|---|---|
| service name or id | required | path | The unique identifier or the name of the Service to create or update. |
| route name or id | required | path | The unique identifier or the name of the Route to create or update. |
Request Body
| Attributes | Mandatory | Description |
|---|---|---|
| name | optional | The Route name |
| protocols | required | A list of the protocols this Route should allow. When set to ["https"], HTTP requests are answered with a request to upgrade to HTTPS. Defaults to ["http", "https"]. |
| methods | semi-optional | A list of HTTP methods that match this Route. |
| hosts | semi-optional | A list of domain names that match this Route. With form-encoded, the notation is hosts[]=example.com&hosts[]=foo.test. With JSON, use an Array. |
| paths | semi-optional | A list of paths that match this Route. With form-encoded, the notation is paths[]=/foo&paths[]=/bar. With JSON, use an Array. |
| headers | semi-optional | 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. |
| https_redirect_status_code | required | 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. Accepted values are: 426, 301, 302, 307, 308. Defaults to 426. |
| regex_priority | optional | 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). Defaults to 0. |
| strip_path | optional | When matching a Route via one of the paths, strip the matching prefix from the upstream request URL. Defaults to true. |
| path_handling | optional | 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. Accepted values are: "v0", "v1". Defaults to "v0". |
| preserve_host | optional | 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. |
| preserve_host | optional | 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. |
| snis | semi-optional | A list of SNIs that match this Route when using stream routing. |
| sources | semi-optional | 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”. |
| destinations | semi-optional | 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”. |
| tags | optional | An optional set of strings associated with the Route, for grouping and filtering. |
| service | optional | The Service this Route is associated to. This is where the Route proxies traffic to. With form-encoded, the notation is service.id= |
Response
- HTTP 201 Created or HTTP 200 OK
- See POST and PATCH responses.
Request Body
{"host"=>"httpbin.org", "name"=>"httpbin-api", "retries"=>5, "protocol"=>"https", "port"=>443, "path"=>"/", "connect_timeout"=>60000, "write_timeout"=>60000, "read_timeout"=>60000, "tags"=>nil, "client_certificate"=>nil}
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
Content-Type | string |