NSX-T Data Center REST API

Update API service properties

Update the configuration of the NSX API service. Changes are applied to all nodes in the cluster. The API service on each node will restart after it is updated using this API. There may be a delay of up to a minute or so between the time this API call completes and when the new configuration goes into effect. Note that TLSv1.3 cipher suites are not controlled individually but instead toggle based on the setting of the TLSv1.3 protocol version.

Request:

Method:

PUT

URI Path(s):

/api/v1/cluster/api-service

Request Headers:

n/a

Query Parameters:

n/a

Request Body:

ApiServiceConfig+

ApiServiceConfig (schema)

Name	Description	Type	Notes
_create_time	Timestamp of resource creation	EpochMsTimestamp	Readonly Sortable
_create_user	ID of the user who created this resource	string	Readonly
_last_modified_time	Timestamp of last modification	EpochMsTimestamp	Readonly Sortable
_last_modified_user	ID of the user who last modified this resource	string	Readonly
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_protection	Indicates protection status of this resource Protection status is one of the following: PROTECTED - the client who retrieved the entity is not allowed to modify it. NOT_PROTECTED - the client who retrieved the entity is allowed to modify it REQUIRE_OVERRIDE - the client who retrieved the entity is a super user and can modify it, but only when providing the request header X-Allow-Overwrite=true. UNKNOWN - the _protection field could not be determined for this entity.	string	Readonly
_revision	Generation of this resource config The _revision property describes the current revision of the resource. To prevent clients from overwriting each other's changes, PUT operations must include the current _revision of the resource, which clients should obtain by issuing a GET operation. If the _revision provided in a PUT request is missing or stale, the operation will be rejected.	int
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
_system_owned	Indicates system owned resource	boolean	Readonly
basic_authentication_enabled	Enable or disable basic authentication Identifies whether basic authentication is enabled or disabled in API calls.	boolean	Default: "True"
cipher_suites	Cipher suites used to secure contents of connection The TLS cipher suites that the API service will negotiate.	array of CipherSuite	Minimum items: 1
client_api_concurrency_limit	Client API concurrency limit in calls A per-client concurrency limit. This is the maximum number of outstanding requests that a client can have. For example, a client can open multiple connections to NSX and submit operations on each connection. When this limit is exceeded, the server returns a 503 Service Unavailable error to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "40"
client_api_rate_limit	Client API rate limit in calls per second The maximum number of API requests that will be serviced per second for a given authenticated client. If more API requests are received than can be serviced, a 429 Too Many Requests HTTP response will be returned. To disable API rate limiting, set this value to 0.	integer	Minimum: 0 Default: "100"
connection_timeout	NSX connection timeout NSX connection timeout, in seconds. To disable timeout, set to 0.	integer	Minimum: 0 Maximum: 2147483647 Default: "30"
cookie_based_authentication_enabled	Enable or disable cookie-based authentication Identifies whether cookie-based authentication is enabled or disabled in API calls. When cookie-based authentication is disabled, new sessions cannot be created via /api/session/create.	boolean	Default: "True"
description	Description of this resource	string	Maximum length: 1024 Sortable
display_name	Identifier to use when displaying entity in logs or GUI Defaults to ID if not set	string	Maximum length: 255 Sortable
global_api_concurrency_limit	Global API concurrency limit in calls The maximum number of concurrent API requests that will be serviced. If the number of API requests being processed exceeds this limit, new API requests will be refused and a 503 Service Unavailable response will be returned to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "199"
id	Unique identifier of this resource	string	Sortable
lockout_immune_addresses	IP addresses which are not subject to lockout on failed login attempts The list of IP addresses which are not subjected to a lockout on failed login attempts.	array of IPAddress
protocol_versions	TLS protocol versions The TLS protocol versions that the API service will negotiate.	array of ProtocolVersion	Minimum items: 1
redirect_host	Hostname/IP to use in redirect headers Host name or IP address to use for redirect location headers, or empty string to derive from current request. To disable, set redirect_host to the empty string ("").	HostnameOrIPv4AddressOrEmptyString	Default: ""
resource_type	Must be set to the value ApiServiceConfig	string
session_timeout	NSX session inactivity timeout	integer	Minimum: 0 Maximum: 2147483647 Default: "1800"
tags	Opaque identifiers meaningful to the API user	array of Tag	Maximum items: 30

Example Request:

{ "global_api_concurrency_limit": 199, "client_api_rate_limit": 100, "client_api_concurrency_limit": 40, "connection_timeout": 30, "redirect_host": "", "cipher_suites": [ {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_256_GCM_SHA384"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_128_GCM_SHA256"} {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384}", {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA256"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_128_CBC_SHA256"}, {"enabled": false, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"}, {"enabled": false, "name": "TLS_RSA_WITH_AES_128_CBC_SHA"}, {"enabled": true, "name": "TLS_AES_128_GCM_SHA256"}, {"enabled": true, "name": "TLS_AES_256_GCM_SHA384"} ], "protocol_versions": [ {"enabled": false, "name": "TLSv1.1"}, {"enabled": true, "name": "TLSv1.2"} {"enabled": true, "name": "TLSv1.3"} ] }

Successful Response:

Response Code:

202 Accepted

Response Headers:

Content-type: application/json

Response Body:

ApiServiceConfig+

ApiServiceConfig (schema)

Name	Description	Type	Notes
_create_time	Timestamp of resource creation	EpochMsTimestamp	Readonly Sortable
_create_user	ID of the user who created this resource	string	Readonly
_last_modified_time	Timestamp of last modification	EpochMsTimestamp	Readonly Sortable
_last_modified_user	ID of the user who last modified this resource	string	Readonly
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_protection	Indicates protection status of this resource Protection status is one of the following: PROTECTED - the client who retrieved the entity is not allowed to modify it. NOT_PROTECTED - the client who retrieved the entity is allowed to modify it REQUIRE_OVERRIDE - the client who retrieved the entity is a super user and can modify it, but only when providing the request header X-Allow-Overwrite=true. UNKNOWN - the _protection field could not be determined for this entity.	string	Readonly
_revision	Generation of this resource config The _revision property describes the current revision of the resource. To prevent clients from overwriting each other's changes, PUT operations must include the current _revision of the resource, which clients should obtain by issuing a GET operation. If the _revision provided in a PUT request is missing or stale, the operation will be rejected.	int
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
_system_owned	Indicates system owned resource	boolean	Readonly
basic_authentication_enabled	Enable or disable basic authentication Identifies whether basic authentication is enabled or disabled in API calls.	boolean	Default: "True"
cipher_suites	Cipher suites used to secure contents of connection The TLS cipher suites that the API service will negotiate.	array of CipherSuite	Minimum items: 1
client_api_concurrency_limit	Client API concurrency limit in calls A per-client concurrency limit. This is the maximum number of outstanding requests that a client can have. For example, a client can open multiple connections to NSX and submit operations on each connection. When this limit is exceeded, the server returns a 503 Service Unavailable error to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "40"
client_api_rate_limit	Client API rate limit in calls per second The maximum number of API requests that will be serviced per second for a given authenticated client. If more API requests are received than can be serviced, a 429 Too Many Requests HTTP response will be returned. To disable API rate limiting, set this value to 0.	integer	Minimum: 0 Default: "100"
connection_timeout	NSX connection timeout NSX connection timeout, in seconds. To disable timeout, set to 0.	integer	Minimum: 0 Maximum: 2147483647 Default: "30"
cookie_based_authentication_enabled	Enable or disable cookie-based authentication Identifies whether cookie-based authentication is enabled or disabled in API calls. When cookie-based authentication is disabled, new sessions cannot be created via /api/session/create.	boolean	Default: "True"
description	Description of this resource	string	Maximum length: 1024 Sortable
display_name	Identifier to use when displaying entity in logs or GUI Defaults to ID if not set	string	Maximum length: 255 Sortable
global_api_concurrency_limit	Global API concurrency limit in calls The maximum number of concurrent API requests that will be serviced. If the number of API requests being processed exceeds this limit, new API requests will be refused and a 503 Service Unavailable response will be returned to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "199"
id	Unique identifier of this resource	string	Sortable
lockout_immune_addresses	IP addresses which are not subject to lockout on failed login attempts The list of IP addresses which are not subjected to a lockout on failed login attempts.	array of IPAddress
protocol_versions	TLS protocol versions The TLS protocol versions that the API service will negotiate.	array of ProtocolVersion	Minimum items: 1
redirect_host	Hostname/IP to use in redirect headers Host name or IP address to use for redirect location headers, or empty string to derive from current request. To disable, set redirect_host to the empty string ("").	HostnameOrIPv4AddressOrEmptyString	Default: ""
resource_type	Must be set to the value ApiServiceConfig	string
session_timeout	NSX session inactivity timeout	integer	Minimum: 0 Maximum: 2147483647 Default: "1800"
tags	Opaque identifiers meaningful to the API user	array of Tag	Maximum items: 30

Response Code:

200 OK

Response Headers:

Content-type: application/json

Response Body:

ApiServiceConfig+

ApiServiceConfig (schema)

Name	Description	Type	Notes
_create_time	Timestamp of resource creation	EpochMsTimestamp	Readonly Sortable
_create_user	ID of the user who created this resource	string	Readonly
_last_modified_time	Timestamp of last modification	EpochMsTimestamp	Readonly Sortable
_last_modified_user	ID of the user who last modified this resource	string	Readonly
_links	References related to this resource The server will populate this field when returing the resource. Ignored on PUT and POST.	array of ResourceLink	Readonly
_protection	Indicates protection status of this resource Protection status is one of the following: PROTECTED - the client who retrieved the entity is not allowed to modify it. NOT_PROTECTED - the client who retrieved the entity is allowed to modify it REQUIRE_OVERRIDE - the client who retrieved the entity is a super user and can modify it, but only when providing the request header X-Allow-Overwrite=true. UNKNOWN - the _protection field could not be determined for this entity.	string	Readonly
_revision	Generation of this resource config The _revision property describes the current revision of the resource. To prevent clients from overwriting each other's changes, PUT operations must include the current _revision of the resource, which clients should obtain by issuing a GET operation. If the _revision provided in a PUT request is missing or stale, the operation will be rejected.	int
_schema	Schema for this resource	string	Readonly
_self	Link to this resource	SelfResourceLink	Readonly
_system_owned	Indicates system owned resource	boolean	Readonly
basic_authentication_enabled	Enable or disable basic authentication Identifies whether basic authentication is enabled or disabled in API calls.	boolean	Default: "True"
cipher_suites	Cipher suites used to secure contents of connection The TLS cipher suites that the API service will negotiate.	array of CipherSuite	Minimum items: 1
client_api_concurrency_limit	Client API concurrency limit in calls A per-client concurrency limit. This is the maximum number of outstanding requests that a client can have. For example, a client can open multiple connections to NSX and submit operations on each connection. When this limit is exceeded, the server returns a 503 Service Unavailable error to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "40"
client_api_rate_limit	Client API rate limit in calls per second The maximum number of API requests that will be serviced per second for a given authenticated client. If more API requests are received than can be serviced, a 429 Too Many Requests HTTP response will be returned. To disable API rate limiting, set this value to 0.	integer	Minimum: 0 Default: "100"
connection_timeout	NSX connection timeout NSX connection timeout, in seconds. To disable timeout, set to 0.	integer	Minimum: 0 Maximum: 2147483647 Default: "30"
cookie_based_authentication_enabled	Enable or disable cookie-based authentication Identifies whether cookie-based authentication is enabled or disabled in API calls. When cookie-based authentication is disabled, new sessions cannot be created via /api/session/create.	boolean	Default: "True"
description	Description of this resource	string	Maximum length: 1024 Sortable
display_name	Identifier to use when displaying entity in logs or GUI Defaults to ID if not set	string	Maximum length: 255 Sortable
global_api_concurrency_limit	Global API concurrency limit in calls The maximum number of concurrent API requests that will be serviced. If the number of API requests being processed exceeds this limit, new API requests will be refused and a 503 Service Unavailable response will be returned to the client. To disable API concurrency limiting, set this value to 0.	integer	Minimum: 0 Default: "199"
id	Unique identifier of this resource	string	Sortable
lockout_immune_addresses	IP addresses which are not subject to lockout on failed login attempts The list of IP addresses which are not subjected to a lockout on failed login attempts.	array of IPAddress
protocol_versions	TLS protocol versions The TLS protocol versions that the API service will negotiate.	array of ProtocolVersion	Minimum items: 1
redirect_host	Hostname/IP to use in redirect headers Host name or IP address to use for redirect location headers, or empty string to derive from current request. To disable, set redirect_host to the empty string ("").	HostnameOrIPv4AddressOrEmptyString	Default: ""
resource_type	Must be set to the value ApiServiceConfig	string
session_timeout	NSX session inactivity timeout	integer	Minimum: 0 Maximum: 2147483647 Default: "1800"
tags	Opaque identifiers meaningful to the API user	array of Tag	Maximum items: 30

Example Response:

{ "global_api_concurrency_limit": 199, "client_api_rate_limit": 100, "client_api_concurrency_limit": 40, "connection_timeout": 30, "redirect_host": "", "cipher_suites": [ {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_256_GCM_SHA384"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_128_GCM_SHA256"} {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384}", {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA256"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_256_CBC_SHA"}, {"enabled": true, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256"}, {"enabled": true, "name": "TLS_RSA_WITH_AES_128_CBC_SHA256"}, {"enabled": false, "name": "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA"}, {"enabled": false, "name": "TLS_RSA_WITH_AES_128_CBC_SHA"}, {"enabled": true, "name": "TLS_AES_128_GCM_SHA256"}, {"enabled": true, "name": "TLS_AES_256_GCM_SHA384"} ], "protocol_versions": [ {"enabled": false, "name": "TLSv1.1"}, {"enabled": true, "name": "TLSv1.2"} {"enabled": true, "name": "TLSv1.3"} ] }

Required Permissions:

crud

Feature:

system_administration

Additional Errors:

• 301 Moved Permanently
• 307 Temporary Redirect
• 400 Bad Request
• 403 Forbidden
• 409 Conflict
• 412 Precondition Failed
• 500 Internal Server Error
• 503 Service Unavailable