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",