Overview of Rest APIs
The clients of VMware Aria Operations for Networks API implement a REST workflow making HTTP requests to the server and retrieving the information they need from the server's responses.
About REST
REST, an acronym for Representational State Transfer, describes an architectural style characteristic of applications that use the Hypertext Transfer Protocol (HTTP) to exchange serialized representations of objects between a client and a server. In the VMware Aria Operations for Networks API, these representations are JSON documents.In a REST workflow, object representations are passed back and forth between a client and a server with the explicit assumption that neither party need know anything about an object other than what is presented in a single request or response. The URLs at which these documents are available often persist beyond the lifetime of the request or response that includes them.
VMware Aria Operations for Networks API Reference is available at:
https://developer.vmware.com/apis/224/vrni
The API Reference is also available in the product at:
https://operations-for-networks.your_domain.com/doc-api/index.html
REST API Workflows
Applications that use a REST API send HTTP requests. A script or other higher-level language runs the HTTP requests to make remote procedure calls. These procedure calls create, retrieve, update, or delete objects that the API defines. In the VMware Aria Operations for Networks REST API, these objects are defined by a collection of JSON schemas. The operations themselves are HTTP requests, and so are generic to all HTTP clients. To write a REST API client application, you must understand only the HTTP protocol, and the semantics of JSON, the transfer format that the VMware Aria Operations for Networks API uses. To use the API effectively in such a client, you must become familiar with the following concepts.
-
The set of objects that the API supports, and what they represent.
-
How the API represents these objects.
-
How a client refers to an object on which it wants to operate. The API reference includes a complete list of API requests and model objects.
API Request
The following HTTP headers are typically included in API requests:
|
Request Header |
Description |
|---|---|
|
Authorization |
All requests must include an Authorization header with the authentication token generated from VMware Aria Operations for Networks auth API. |
|
Content-Type |
Requests that include a body must include HTTP Content-Type: application/json header. |
Request Body
Ensure that the content in the request body conforms to the type constraint in the model objects in API Reference
API Response
VMware Aria Operations for Networks uses conventional HTTP response codes to indicate the success or failure of an API request.
-
2xx range indicates success.
-
4xx range indicates an error when the information provided is incorrect. For example, a required parameter was omitted.
-
5xx range indicates an error with VMware Aria Operations for Networks server. However, these errors are rare.
HTTP Response Codes
An API client can expect a subset of HTTP status codes in a response.
|
Status Code |
Status Description |
|---|---|
|
200 OK |
The request is valid and was completed. The response includes a document body |
|
201 Created |
The request is valid. The requested object was created. |
|
204 No Content |
The request is valid and was completed. The response does not include a body. |
|
400 Bad Request |
The request body is malformed, incomplete, or otherwise invalid. |
|
401 Unauthorized |
Login failed or authentication token has expired. |
|
403 Forbidden |
The user is not authenticated or does not have adequate privileges to access one or more objects specified in the request. |
|
404 Not Found |
The object specified in the request cannot be found |
|
405 Method Not Allowed |
The HTTP method specified in the request is not supported for this object. |
|
412 Precondition Failed |
The maximum limit for unique active sessions is reached |
|
415 Unsupported Media Type |
The resource identified by the request does not support a request of the specified Content-Type and HTTP method. |
|
429 Too Many Requests |
A client has sent too many requests or multiple clients are sending too many simultaneous requests and the server is unable to process them due to rate limits. To work around the problem, try sending the request again later. |
|
500 Internal Server Error |
The request was received but cannot be completed because of an internal error on the server. |
|
503 Service Unavailable |
The server is unable to handle the request due to a temporary condition such as resource exhaustion or server maintenance |
API Request Limits
-
The maximum limit for unique active sessions is 100. When you reach the limit, you get a response code 412.
-
The overall system limit for the maximum number of API requests per second is 100. When you reach the system limit, you get a response code 429.
In addition to above limits there are separate rate limits for different categories of API, which are as follows:
|
Category |
Request per second limit |
|---|---|
|
Applications APIs |
20 |
|
Applications Flows APIs |
1 |
|
Applications Flows APIs |
20 |
|
Data Sources APIs |
20 |
|
Entitites APIs |
50 |
|
Search APIs |
50 |
|
Microsegmentation APIs |
20 |
|
Authentication APIs |
20 |
|
Schema APIs |
20 |
|
Metrics APIs |
20 |
|
Default for all other APIs |
20 |