Create a new Service

Create a new Service

post

Path Parameters

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Body

application/json

Description of the new Service for creation

Service

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.

* Additional properties are NOT allowed.
ca_certificatesarray[string]

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

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters
connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

>= 1<= 2147483646

created_atinteger

Unix epoch when the resource was created.

enabledboolean

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.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

A string representing a UUID (universally unique identifier).

>= 1 characters

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

>= 0<= 65535

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

>= 0<= 32767

tagsarray[string]

A string representing a tag.

tls_sansobject

Additional Subject Alternative Names that can be matched on Upstream server’s TLS certificate (in addition to host).

Show Child Parameters
tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

>= 0<= 64

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

Response

application/json

Successfully created Service

Service

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.

* Additional properties are NOT allowed.
ca_certificatesarray[string]

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

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters
connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

>= 1<= 2147483646

created_atinteger

Unix epoch when the resource was created.

enabledboolean

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.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

A string representing a UUID (universally unique identifier).

>= 1 characters

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

>= 0<= 65535

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

>= 0<= 32767

tagsarray[string]

A string representing a tag.

tls_sansobject

Additional Subject Alternative Names that can be matched on Upstream server’s TLS certificate (in addition to host).

Show Child Parameters
tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

>= 0<= 64

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

post/control-planes/{controlPlaneId}/core-entities/services

Body

{ "host": "example.internal", "id": "49fd316e-c457-481c-9fc7-8079153e4f3c", "name": "example-service", "path": "/", "port": 80, "protocol": "http" }
 
application/json

Delete a Service

Delete a Service

delete

Path Parameters

ServiceIdstringrequired

ID of the Service to lookup

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Response

Successfully deleted Service or the resource didn’t exist

delete/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}
 

Get a Service

Get a Service using ID or name.

get

Path Parameters

ServiceIdstringrequired

ID of the Service to lookup

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Response

application/json

Successfully fetched Service

Service

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.

* Additional properties are NOT allowed.
ca_certificatesarray[string]

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

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters
connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

>= 1<= 2147483646

created_atinteger

Unix epoch when the resource was created.

enabledboolean

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.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

A string representing a UUID (universally unique identifier).

>= 1 characters

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

>= 0<= 65535

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

>= 0<= 32767

tagsarray[string]

A string representing a tag.

tls_sansobject

Additional Subject Alternative Names that can be matched on Upstream server’s TLS certificate (in addition to host).

Show Child Parameters
tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

>= 0<= 64

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

get/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}
 
application/json

Upsert a Service

Create or Update Service using ID or name.

put

Path Parameters

ServiceIdstringrequired

ID of the Service to lookup

Example:7fca84d6-7d37-4a74-a7b0-93e576089a41

controlPlaneIdstring(uuid)required

The UUID of your control plane. This variable is available in the Konnect manager.

Example:9524ec7d-36d9-465d-a8c5-83a3c9390458

Body

application/json

Description of the Service

Service

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.

* Additional properties are NOT allowed.
ca_certificatesarray[string]

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

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters
connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

>= 1<= 2147483646

created_atinteger

Unix epoch when the resource was created.

enabledboolean

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.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

A string representing a UUID (universally unique identifier).

>= 1 characters

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

>= 0<= 65535

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

>= 0<= 32767

tagsarray[string]

A string representing a tag.

tls_sansobject

Additional Subject Alternative Names that can be matched on Upstream server’s TLS certificate (in addition to host).

Show Child Parameters
tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

>= 0<= 64

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

Response

application/json

Successfully upserted Service

Service

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.

* Additional properties are NOT allowed.
ca_certificatesarray[string]

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

client_certificateobject

Certificate to be used as client certificate while TLS handshaking to the upstream server.

Show Child Parameters
connect_timeoutinteger

The timeout in milliseconds for establishing a connection to the upstream server.

Default:60000

>= 1<= 2147483646

created_atinteger

Unix epoch when the resource was created.

enabledboolean

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.

Default:true

hoststringrequired

The host of the upstream server. Note that the host value is case sensitive.

idstring

A string representing a UUID (universally unique identifier).

>= 1 characters

namestring

The Service name.

pathstring

The path to be used in requests to the upstream server.

portinteger

The upstream server port.

Default:80

>= 0<= 65535

protocolstring

The protocol used to communicate with the upstream.

Allowed values:grpcgrpcshttphttpstcptlstls_passthroughudpwswss

Default:http

read_timeoutinteger

The timeout in milliseconds between two successive read operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

retriesinteger

The number of retries to execute upon failure to proxy.

Default:5

>= 0<= 32767

tagsarray[string]

A string representing a tag.

tls_sansobject

Additional Subject Alternative Names that can be matched on Upstream server’s TLS certificate (in addition to host).

Show Child Parameters
tls_verifyboolean

Whether to enable verification of upstream server TLS certificate. If set to null, then the Nginx default is respected.

tls_verify_depthinteger

Maximum depth of chain while verifying Upstream server’s TLS certificate. If set to null, then the Nginx default is respected.

>= 0<= 64

updated_atinteger

Unix epoch when the resource was last updated.

urlstring

Helper field to set protocol, host, port and path using a URL. This field is write-only and is not returned in responses.

write_timeoutinteger

The timeout in milliseconds between two successive write operations for transmitting a request to the upstream server.

Default:60000

>= 1<= 2147483646

put/control-planes/{controlPlaneId}/core-entities/services/{ServiceId}

Body

{ "host": "example.internal", "id": "49fd316e-c457-481c-9fc7-8079153e4f3c", "name": "example-service", "path": "/", "port": 80, "protocol": "http" }
 
application/json

Targets

A target is an IP address or 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, or use the DELETE method to accomplish the same.