NSX-T API Guide

3821 Pages·2017·11.12 MB·English

Copyright © 2014-2017 VMware, Inc. All rights reserved. Copyright and trademark information.
EN-002322-00
NSX-T API Guide
NSX-T 1.1.0
Table of Contents
1 Overview
2 API Methods
5.1 Licensing
5.2 Nsx Admin
5.23.1 Appliance Management
5.23.2 Backup Config
5.23.3 Cluster Management
5.3 Users and Roles
5.4 Aggregation Service
5.23.1 Configuration
5.5 Api Services
5.23.1 Api Request Batching
5.23.2 Authentication
5.23.3 Task Management
5.6 Associations
5.7 Error Resolver
5.8 Fabric
5.23.1 Nodes
5.23.2 Vifs
5.23.3 Virtual Machines
5.9 Grouping Objects
5.23.1 Ip Sets
5.23.2 Mac Sets
5.23.3 Ns Groups
5.23.4 Ns Service Groups
5.23.5 Ns Services
5.10 Licensing
5.11 Logical Routing And Services
5.23.1 Bfd Peers
5.23.2 Dhcp Relay
5.23.3 Dhcp Relay Profiles
5.23.4 Logical Router Ports
5.23.5 Logical Routers
5.23.6 Nat
5.23.7 Routing Bfd Configuration
5.23.8 Routing Configuration
5.23.9 Service Profiles
5.23.10 Services
5.12 Logical Switching
5.23.1 Logical Switch Ports
5.23.2 Logical Switches
5.23.3 Switching Profiles
5.13 Network Transport
5.23.1 Bridge Clusters
5.23.2 Bridge Endpoints
5.23.3 Cluster Profiles
5.23.4 Edge Clusters
5.23.5 Hostswitch Profiles
5.23.6 Transport Nodes
5.23.7 Transport Profiles
5.23.8 Transport Zones
5.14 Normalization
5.15 Nsx Component Administration
5.23.1 Appliance Management
5.23.2 Cluster Management
5.23.3 Trust Management
5.23.3.1 Certificate
5.23.3.2 Crl
5.23.3.3 Csr
5.16 Operations
5.23.1 Ipfix
5.17 Pool Management
5.23.1 Ip Pools
5.23.2 Vni Pools
5.18 Realization
5.19 Services
5.23.1 Dhcp
5.23.2 Firewall
5.23.3 Metadata Proxy
5.23.4 Networkencryption
5.20 Transport Entities
5.23.1 Transport-Nodes
5.21 Troubleshooting And Monitoring
5.23.1 Heatmap
5.23.2 Ipfix
5.23.3 Portconnection
5.23.4 Portmirroring
5.23.5 System Logs
5.23.6 Traceflow
5.22 Uirpc
5.23 Upgrade
5.23.1 Bundle
5.23.2 Group
5.23.3 History
5.23.4 Nodes
5.23.5 Plan
5.23.6 Status
5.23.7 Upgradeunits
3 API Types
4 API Type Schemas
5 API Errors
Overview
Introduction
NSX-T provides a programmatic API to automate the management of the node. The API follows a
resource-oriented Representational State Transfer (REST) architecture, using JSON object encoding.
Clients interact with the API using RESTful web service calls over the HTTPS protocol.
Each API method is identified by a request method and URI. Method parameters are specified as
key-value pairs appended to the URI. Unless otherwise noted, request and response bodies are
encoded using JSON, and must conform to the JSON schema associated with each method. The
content type of each request and reply is "application/json" unless otherwise specified. Each request
that can be made is documented in the API Methods section. The associated request and response
body schemas are documented in the API Schemas section.
It is possible for any request to fail. Errors are reported using standard HTTP response codes. It
should be assumed the following errors could be returned by any API method: 301 Moved
Permanently, 307 Temporary Redirect, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500
Internal Server Error, 503 Service Unavailable. Where other errors may be returned, the type of
error is indicated in the API method description. All errors are documented in the API Errors section.
It is possible for requests to partially complete before failing. Any inconsistent state resulting from a
failure must be resolved by the caller.
Request Authentication
Most API calls require authentication. This API supports HTTP Basic authentication and session-
based authentication schemes. Multiple authentication schemes may not be used concurrently.
HTTP Basic Authentication
To authenticate a request using HTTP Basic authentication, the caller's credentials are passed using
the 'Authorization' header. The header content should consist of a base64-encoded string containing
the username and password separated by a single colon (":") character, as specified in RFC 1945
section 11.1.
For example, to authenticate a request using the default credentials of user admin with password
admin, include the following header with the request:
Authorization: Basic YWRtaW46YWRtaW4=
The following cURL command will authenticate to the manager using basic authentication and will
issue a GET request for logical ports:
curl -k -u USERNAME:PASSWORD https://MANAGER/api/v1/logical-ports
where:
USERNAME is the user to authenticate as,
PASSWORD is the password to provide, and
MANAGER is the IP address or host name of the NSX manager
For example:
curl -k -u admin:secretPw99 https://192.168.22.32/api/v1/logical-ports
Note: the -k argument instructs cURL to skip verifying the manager's self-signed X.509 certificate.
Session-based Authentication
Session-based authentication is used by calling the /api/session/create authentication API to
manage a session cookie. The session cookie returned in the result of a successful login must be
provided in subsequent requests in order to associate those requests with the session.
Session state is local to the server responding to the API request. Idle sessions will automatically
time-out, or can be terminated immediately using the POST /logout API.
To obtain a session cookie, POST form data to the server using the application/x-ww-form-
urlencoded media type, with fields "j_username" and "j_password" containing the username and
password. The following cURL command will authenticate to the server and will deposit the session
cookie in the file "cookies.txt":
curl -k -c cookies.txt -X POST -d j_username=USERNAME&j_password=PASSWORD
https://MANAGER/api/session/create
For example:
curl -k -c cookies.txt -X POST -d j_username=admin&j_password=secretPw99
https://192.168.22.32/api/session/create
The manager will respond with the roles and permissions granted to the user, and cURL will deposit
the session cookie into the file "cookies.txt".
In subsequent cURL requests, use the -b argument to specify the cookie file:
curl -k -b cookies.txt -X GET https://192.168.22.32/api/v1/logical-ports
When the session expires, the manager will respond with a 403 Forbidden HTTP response, at which
point you must obtain a new session cookie.
Experimental Features
The following features are experimental and are not fully supported:
Distributed Network Encryption
Hyper-V
MPLS
Example Requests and Responses
Most of the API calls below have example requests and responses. Your actual response might differ
from the example in the number of fields returned because optional empty fields are not returned
when you make an API call.
Restrictions on Certain Fields in a Request
In layer 2 switching, the following fields can contain any character except these 6 characters:
semicolon (;), vertical bar (|), equal sign (=), comma (,), tilde (~), and the "at" sign (@). They also
have a maximum length limitation as specified below:
Logical switch display name. Maximum length: 80 bytes.
Host switch name in TransportZone. Maximum length: 80 bytes.
Uplink name in UplinkHostSwitchProfile. Maximum length: 47 bytes.
OpenAPI Specification of NSX-T API
You can get a OpenAPI specification of the NSX-T API with one of the following calls:
GET https:///api/v1/spec/openapi/nsx_api.yaml
GET https:///api/v1/spec/openapi/nsx_api.json
API Methods Toggle all tables -
Licensing
Associated URIs:
POST /api/v1/licenses
DELETE /api/v1/licenses/<license-key>
GET /api/v1/licenses/<license-key>
Add a new license key
This will add a license key to the system. The API supports adding only one license key for each
license edition type - Standard, Advanced or Enterprise. If a new license key is tried to add for an
edition for which the license key already exists, then this API will return an error.
Request:
Method: POST
URI Path: /api/v1/licenses
Request Headers: n/a
Query Parameters: n/a
Request Body: License -
License (schema)
Name Description Type Notes
_links References related to this resource array of Readonly
ResourceLink
_schema string
_self SelfResourceLink
capacity_type license metric string Readonly
Enum:
VM, CPU,
USER
description license edition string Readonly
expiry date that license expires EpochMsTimestamp Readonly
features semicolon delimited feature list string Readonly
is_eval true for evalution license boolean Readonly
is_expired whether the license has expired boolean Readonly
is_mh multi-hypervisor support boolean Readonly
license_key license key string Required
Pattern:
"^[A-
Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}$"
product_name product name string Readonly
product_version product version string Readonly
quantity license capacity; 0 for unlimited integer Readonly
Example Request:
POST https://<nsx-mgr>/api/v1/licenses
{
"license_key": "11111-22222-33333-44444-55555"
}
Successful Response:
Response Code: 200 OK
Response Headers: Content-type: application/json
Response Body: License -
License (schema)
Name Description Type Notes
_links References related to this resource array of Readonly
ResourceLink
_schema string
_self SelfResourceLink
capacity_type license metric string Readonly
Enum:
VM, CPU,
USER
description license edition string Readonly
expiry date that license expires EpochMsTimestamp Readonly
features semicolon delimited feature list string Readonly
is_eval true for evalution license boolean Readonly
is_expired whether the license has expired boolean Readonly
is_mh multi-hypervisor support boolean Readonly
license_key license key string Required
Pattern:
"^[A-
Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}$"
product_name product name string Readonly
product_version product version string Readonly
quantity license capacity; 0 for unlimited integer Readonly
Example Response:
{
"features":"mh, l2-vlan,l2-vxlan,l3,l2-edge,dfw,efw,lb,vpn,multi-vc,policy,si-
ovsdb,si-guest, si-netx,si-pp,av,dlb,mpls",
"capacity_type": "VM"
"product_version": "1.0",
"quantity": 1,
"is_eval": false,
"description" : "NSX Standard Edition"
"expiry": 1458688231359,
"product_name" : "NSX",
"is_mh": false,
"license_key": "11111-22222-33333-44444-55555"
}
Required Permissions:
read-write-api
Additional Errors:
301 Moved Permanently
307 Temporary Redirect
400 Bad Request
403 Forbidden
500 Internal Server Error
503 Service Unavailable
Remove a license identified by the license-key
This will delete the license key identified in the URI by the and its properties from the system.
Don't allow to delete the last key.
Request:
Method: DELETE
URI Path: /api/v1/licenses/<license-key>
Request Headers: n/a
Query Parameters: n/a
Request Body: n/a
Example Request:
DELETE https://<nsx-mgr>/api/v1/licenses/11111-22222-33333-44444-55555
Successful Response:
Response Code: 200 OK
Response Headers: n/a
Response Body: n/a
Required Permissions:
read-write-api
Additional Errors:
301 Moved Permanently
307 Temporary Redirect
400 Bad Request
403 Forbidden
500 Internal Server Error
503 Service Unavailable
Get license properties for license identified by the license-key
This will get the properties of a particular license idetified in the URI by the
Request:
Method: GET
URI Path: /api/v1/licenses/<license-key>
Request Headers: n/a
Query Parameters: n/a
Request Body: n/a
Example Request:
GET https://<nsx-mgr>/api/v1/licenses/11111-22222-33333-44444-55555
Successful Response:
Response Code: 200 OK
Response Headers: Content-type: application/json
Response Body: License -
License (schema)
Name Description Type Notes
_links References related to this resource array of Readonly
ResourceLink
_schema string
_self SelfResourceLink
capacity_type license metric string Readonly
Enum:
VM, CPU,
USER
description license edition string Readonly
expiry date that license expires EpochMsTimestamp Readonly
features semicolon delimited feature list string Readonly
is_eval true for evalution license boolean Readonly
is_expired whether the license has expired boolean Readonly
is_mh multi-hypervisor support boolean Readonly
license_key license key string Required
Pattern:
"^[A-
Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}-
[A-Z0-
9]{5}$"
product_name product name string Readonly
product_version product version string Readonly
quantity license capacity; 0 for unlimited integer Readonly
Example Response:
{
"features":"mh, l2-vlan,l2-vxlan,l3,l2-edge,dfw,efw,lb,vpn,multi-vc,policy,si-
ovsdb,si-guest, si-netx,si-pp,av,dlb,mpls",
"capacity_type": "VM"
"product_version": "1.0",
"quantity": 1,
"is_eval": false,
"description": "NSX Standard Edition"
"expiry": 1458688231359,
"product_name": "NSX",
"is_mh": false,
"license_key": "11111-22222-33333-44444-55555"
}
Required Permissions:
read-api
Additional Errors:
404 Not Found
301 Moved Permanently
307 Temporary Redirect
400 Bad Request
403 Forbidden
500 Internal Server Error
503 Service Unavailable
Nsx Admin
Nsx Admin: Appliance Management
Associated URIs:
POST /api/v1/node/backups?action=restore
Restore node backup
Restores the NSX Manager state, using backup information from the specified backup file.
Important: This restore request is one part of the restore process. You must complete all
backup and restore tasks in the correct order. See the NSX-T Administration Guide for
information and instructions about performing backups and restores.
Request:
Method: POST
URI Path: /api/v1/node/backups?action=restore
Request Headers: n/a
Query Parameters: n/a
Request Body: RestoreProperties -
RestoreProperties (schema)
Name Description Type Notes
restore_file Restore file LocalFilestoreBackupFile Required
or
RemoteFilestoreBackupFile
Example Request:
POST https://<nsx-mgr>/api/v1/node/backups?action=restore
{
"restore_file":
{
"file_store": "remote",
"passphrase": "backup_secret",
"server": "10.1.1.1",
"uri": "/backups/nsx_node_20151231.bak",
"protocol":
{
"name": "scp",
"ssh_fingerprint": "61158a0316bb060c0a42dbc68b149a88",
"authentication_scheme":
{
"scheme_name": "password",
"username": "scp_user",
"password": "scp_user_password"
}
}
}
}
Successful Response:
Response Code: 200 OK
Response Headers: n/a
Response Body: n/a
Required Permissions:
read-write-api
Additional Errors:
404 Not Found
504 Gateway Timeout
301 Moved Permanently
307 Temporary Redirect
400 Bad Request
403 Forbidden
500 Internal Server Error
503 Service Unavailable
Nsx Admin: Backup Config
Associated URIs:
POST /api/v1/cluster?action=summarize_inventory_to_remote
POST /api/v1/cluster?action=backup_to_remote
GET /api/v1/cluster/backups/config
PUT /api/v1/cluster/backups/config
GET /api/v1/cluster/backups/history
GET /api/v1/cluster/backups/status
Get backup configuration
Get a configuration of a file server and timers for automated backup. Fields that contain secrets
(password, passphrase) are not returned.
Request:
Method: GET
URI Path: /api/v1/cluster/backups/config
Request Headers: n/a
Query Parameters: n/a
Request Body: n/a
Successful Response:
Response Code: 200 OK
Response Headers: Content-type: application/json
Response Body: BackupConfiguration -
BackupConfiguration (schema)
Name Description Type Notes
backup_enabled true if automated backup is boolean Required
enabled Default:
"False"
backup_schedule Set when backups should be BackupSchedule
taken - on a weekly schedule
or at regular intervals.
inventory_summary_interval The minimum number of integer Required
seconds between each upload Minimum:
of the inventory summary to 30
backup server. Maximum:
3600
Default:
"30"
passphrase Passphrase used to encrypt string
backup files.
remote_file_server The server to which backups RemoteFileServer Required
will be sent.
Example Response:
{
"backup_enabled" : true;
"backup_schedule":{
"resource_type": "WeeklyBackupSchedule",
"days_of_week":[
1,
3,
5
],
"hour_of_day":0,
"minute_of_day":0
},
"remote_file_server":{
"server":"10.1.2.3",
"port":22,
"protocol":{
"protocol_name":"sftp",
"ssh_fingerprint":"43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
"authentication_scheme":{
"scheme_name":"password",
"username":"admin"
}
},
"directory_path":"/nsx-backups"
},
"inventory_summary_interval":300
}
Required Permissions:
read-api
Additional Errors:
301 Moved Permanently
307 Temporary Redirect
400 Bad Request
403 Forbidden
500 Internal Server Error
503 Service Unavailable
Configure backup
Configure file server and timers for automated backup. If secret fields are omitted (password,
passphrase) then use the previously set value.
Request:
Method: PUT
URI Path: /api/v1/cluster/backups/config
Request Headers: n/a
Query Parameters: n/a
Request Body: BackupConfiguration -
BackupConfiguration (schema)
Name Description Type Notes
backup_enabled true if automated backup is boolean Required
enabled Default:
"False"
backup_schedule Set when backups should be BackupSchedule
taken - on a weekly schedule
or at regular intervals.
inventory_summary_interval The minimum number of integer Required
seconds between each upload Minimum:
of the inventory summary to 30
backup server. Maximum:
3600
Default:
"30"
passphrase Passphrase used to encrypt string
backup files.
remote_file_server The server to which backups RemoteFileServer Required
will be sent.
Example Request:
PUT https://<nsx-mgr>/api/v1/backups/config
{
"backup_enabled" : true;
"backup_schedule":{
"resource_type": "WeeklyBackupSchedule",
"days_of_week":[
1,
3,
5
],
"hour_of_day":0,
"minute_of_day":0
},
"remote_file_server":{
"server":"10.1.2.3",
"port":22,
"protocol":{
"protocol_name":"sftp",
"ssh_fingerprint":"43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
"authentication_scheme":{
"scheme_name":"password",
"username":"admin",
"password":"default"
}
},
"directory_path":"/nsx-backups"
},
"passphrase":"swordfish",
"inventory_summary_interval":300
}|
PUT https://<nsx-mgr>/api/v1/backups/config
{
"backup_enabled" : true;
"interval_config":{
"resource_type": "IntervalBackupSchedule",
"seconds_between_backups":90
},
"remote_file_server":{
"server":"10.1.2.3",
"port":22,
"protocol":{
"protocol_name":"sftp",
"ssh_fingerprint":"43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
"authentication_scheme":{
"scheme_name":"password",
"username":"admin",
"password":"default"
}
},
"directory_path":"/nsx-backups"
},
"passphrase":"swordfish",