Arista Networks NetVisor OS REST API Guide 7.0.2

REST API Clients

The REST API does not have a client-side library. Clients use HTTP or HTTPS with the URIs listed in the contract and then handle request and response payloads that follow the JSON schema as described with each URI in the contract. Typically, REST APIs are implemented within Web frameworks and facilitate the use of URIs and the handling of JSON. It is not required for the REST API client to run on the Arista Networks switch.

Swagger provides the documentation, and you use the Swagger JavaScript client in a Web browser.

Swagger, designed for REST API documentation and the JavaScript client, provides a convenient and quick way to display REST URIs and JSON, as well as a way to test a URI. 

You can also use your favorite HTTP client tool, such as cURL.

See cUrl examples for more information.

The REST API defines a contract based on HTTP verbs, URIs, and a JSON schema. 

REST API Clients use HTTP or HTTPS with HTTP verbs and URIs listed in the contract and handle the request and response payloads according to the JSON format for the URIs.

For example, if you want to configure a REST API operation to lookup a vFlow, it should have the following format:

The REST API client reads the documentation to understand what HTTP verb and URI is used to look up a vFlow and also the format of the JSON request and response payloads. 

In the example, GET is the HTTP verb, and the URI is vflows/name/my-vflow which identifies a resource: a vFlow uniquely identified as my-flow. The request does not have a payload while the response contains the my-vflow data and the result status is in JSON format.

The main elements of a RESTful API implementation are:

•Resources – A resource is the first key element. You want to create a VLAN on a switch, and the URL of the switch is http://<switch-ip>. In order to create a VLAN using REST, you can issue the command http://<switch-ip>/vREST/vlans. This command creates the vlan per the settings in the Parameter body field.

•Request Verbs – They describe what the resource is going to be used to do. To request data from an endpoint, a browser issues a GET verb. Other verbs include POST, PUT, and DELETE. So, in the case of the example http://<switch-ip>/vRest/vlans, the Web browser issues a POST verb to configure a VLAN. See VLAN example.

•Request Headers – Additional instructions may be included with the request, such as the type of response required or authorization information. Further instructions may be included with the request, such as the type of response required or authorization information.

•Request Body – The actual data sent with the request. A POST request to a switch normally includes data in the request. The client actually tells the switch that it wants to add a resource through a POST call. As a result, the request body contains details of the resource that needs to be added to the switch.

•Response Body – The main body of the response contains the details of the request.

•Response Status codes – A web server returns these general codes along with a response. For example, code 200 is sent in the response message to the client when there is no error.

Restful Methods

The following is a list of actions of the respective verbs are sent by the client to the RESTFul web service.

•POST – Creates a configuration.

•GET – Used to obtain a list of all configured parameters.

•PUT – Adds the given information to the specified object and returns a 404 Resource Not Found error if the object does not exist.

•DELETE – Deletes a configuration.

HTTP Response Codes

The REST API follows the conventions of the RESTful style for HTTP response status codes. The following is a list of status codes for known use cases:

•200 (OK) – successful completion of the REST API operation.

•201 (Created) – successful completion of a new resource completion.

•401 (Unauthorized) – unsuccessful authentication with Arista NetVisor OS.

•403 (Forbidden) – authentication is successful however the command failed to execute. Details are provided.

•404 (Not Found) – the URI cannot map to a resource. You may see this message returned by Apache CXF runtime.

•415 (Unsupported Media Type) – media type is unsupported. You may see this returned by Apache CXF runtime if a request for application/xml, for example, is received.

•500 (Internal Server Error) – indicates a general server-side problem with either PN REST API servlet or Arista NetVisor OS.

Response Payloads

All Arista NetVisor OS REST APIs return a response payload with the following schema:

The response payload may contain data, and always contains result. 

Conventions

•The data consists of one or more resources of the same type. 

•The result always contains responseCode which is a valid HTTP response status 

•code and status which is the status of the back-end operation on Arista NetVisor OS as either SUCCESS or FAILURE. 

•The result may contain a code number or a message that provides further information about the back-end operation on Arista NetVisor OS, such as the next value or an error.

REST API clients should check both the HTTP status code returned in the response Status-Line and the responseCode returned in the result. 

When the message in the status code response is "Success", the Response Code is either 200 or 201. 

In the event of a "Failure" message in the status code, check for the specific Response Code to diagnose the problem. In some cases, data may contain a partial result.