Sign in
Services

Upsert a Service

Create or Update Service using ID or name.

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

Request body

ca_certificatesstring[] nullable

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

connect_timeoutinteger nullable

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

created_atinteger nullable

Unix epoch when the resource was created.

enabledboolean nullable

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.

hoststring required

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

idstring nullable

A string representing a UUID (universally unique identifier).

namestring nullable

The Service name.

pathstring nullable

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

portinteger nullable

The upstream server port.

protocol'grpc' | 'grpcs' | 'http' | 'https' | 'tcp' | 'tls' | 'tls_passthrough' | 'udp' | 'ws' | 'wss' nullable

The protocol used to communicate with the upstream.

read_timeoutinteger nullable

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

retriesinteger nullable

The number of retries to execute upon failure to proxy.

tagsstring[] nullable

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

tls_verifyboolean nullable

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

tls_verify_depthinteger nullable

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

updated_atinteger nullable

Unix epoch when the resource was last updated.

urlstring nullable

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 nullable

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

Example request

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

Response

Successfully upserted Service

ca_certificatesstring[] nullable

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

connect_timeoutinteger nullable

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

created_atinteger nullable

Unix epoch when the resource was created.

enabledboolean nullable

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.

hoststring required

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

idstring nullable

A string representing a UUID (universally unique identifier).

namestring nullable

The Service name.

pathstring nullable

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

portinteger nullable

The upstream server port.

protocol'grpc' | 'grpcs' | 'http' | 'https' | 'tcp' | 'tls' | 'tls_passthrough' | 'udp' | 'ws' | 'wss' nullable

The protocol used to communicate with the upstream.

read_timeoutinteger nullable

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

retriesinteger nullable

The number of retries to execute upon failure to proxy.

tagsstring[] nullable

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

tls_verifyboolean nullable

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

tls_verify_depthinteger nullable

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

updated_atinteger nullable

Unix epoch when the resource was last updated.

urlstring nullable

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 nullable

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

Example response

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

Changes

Changed in 6 of the 75 revisions of this API.91249

  • c83332d134eb11See the full diff
    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ○

      the request property became nullable

      request-property-became-nullable

  • 845120e19d453See the full diff
    • ▲

      the request property / became not nullable

      request-property-became-not-nullable

    • ▲

      the request property / became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

  • ddf026fbd25b112See the full diff
    • ▲

      the request property's minLength was increased from 0 to 1

      request-property-min-length-increased

    • ●

      the request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the request property's max was set to 65535.00

      request-property-max-set

    • ●

      the request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the request property's max was set to 32767.00

      request-property-max-set

    • ●

      the request property's max was set to 64.00

      request-property-max-set

    • ●

      the request property's max was set to 2147483646.00

      request-property-max-set

    • ●

      the request property's min was set to 1.00

      request-property-min-set

    • ●

      the request property's min was set to 0.00

      request-property-min-set

    • ●

      the request property's min was set to 1.00

      request-property-min-set

    • ●

      the request property's min was set to 0.00

      request-property-min-set

    • ●

      the request property's min was set to 0.00

      request-property-min-set

    • ●

      the request property's min was set to 1.00

      request-property-min-set

  • 3c0154b2053a317See the full diff
    • ▲

      the response property / became nullable for the status

      response-property-became-nullable

    • ▲

      the response property / became nullable for the status

      response-property-became-nullable

    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ○

      the request property / became nullable

      request-property-became-nullable

    • ○

      the request property / became nullable

      request-property-became-nullable

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      the request property default value true was added

      request-property-default-value-added

    • ○

      the request property default value 80 was added

      request-property-default-value-added

    • ○

      the request property default value http was added

      request-property-default-value-added

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      the request property default value 5 was added

      request-property-default-value-added

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value true was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 80 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value http was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 5 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6333a0d3b09514See the full diff
    • ○

      the request property default value 60000 was removed

      request-property-default-value-removed

    • ○

      the request property default value true was removed

      request-property-default-value-removed

    • ○

      the request property default value 80 was removed

      request-property-default-value-removed

    • ○

      the request property default value http was removed

      request-property-default-value-removed

    • ○

      the request property default value 60000 was removed

      request-property-default-value-removed

    • ○

      the request property default value 5 was removed

      request-property-default-value-removed

    • ○

      the request property default value 60000 was removed

      request-property-default-value-removed

    • ○

      the response's property default value 60000 was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value true was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value 80 was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value http was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value 60000 was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value 5 was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value 60000 was removed for the status

      response-property-default-value-removed

    This revision also has 15 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 76b0fefddb0d117See the full diff
    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      the request property default value true was added

      request-property-default-value-added

    • ○

      the request property default value 80 was added

      request-property-default-value-added

    • ○

      the request property default value http was added

      request-property-default-value-added

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      the request property default value 5 was added

      request-property-default-value-added

    • ○

      the request property default value 60000 was added

      request-property-default-value-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value true was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 80 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value http was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 5 was added for the status

      response-property-default-value-added

    • ○

      the response's property default value 60000 was added for the status

      response-property-default-value-added