REST API Design
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 Pluribus 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:
GET /vflows/name/asdasd (where the name of the vFlow is asdasd)
URL = http://10.110.0.56:80/vRest/vflows/name/asdasd
{"vflow":{"name":"asdasd","id":"c000184:52","scope":"local","type":"vflow","hidden":false,"burst-size":0,"precedence":2,"log-stats":true,"stats-interval":60,"hw-stats":true,"enable":true,"table-name":"System-L1-L4-Tun-1-0"}}{"result":{"api.switch-name":"local","scope":"local","status":"Success","code":0,"message":""}}
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 key elements of a RESTful implementation are as follows:
- Resources – The first key element is the resource itself. 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 – These describe what you want to do with the resource. A browser issues a GET verb to instruct the endpoint it wants to get data. However, there are many other verbs available including things like POST, PUT, and DELETE. So in the case of the example http://<switch-ip>/vRest/vlans, the Web browser issues a POST verb because you want to configure a vlan. See VLAN example.
- Request Headers – These are additional instructions sent with the request. These might define the type of response required or the authorization details.
- Request Body – Data is sent with the request. Data is normally sent in the request when a POST request is sent to the switch. In a POST call, the client actually tells the switch that it wants to add a resource to the switch. Therefore, the request body has the details of the required resource added to the switch.
- Response Body – This is the main body of the response and returns the details of the request.
- Response Status codes – These codes are the general codes which are returned along with the response from the web server. An example is the code 200 which is normally returned if there is no error when returning a response to the client.
Restful Methods
The following is a list of actions of the respective verbs are sent by the client.
- POST – used to create a configuration using the RESTful Web service.
- GET – used to get a list of all configured parameters using the RESTful Web service.
- PUT – Adds the supplied information to the specified object; returns a 404 Resource Not Found error if the object does not exist.
- DELETE – used to delete a configuration using the RESTful web service.
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 Netvisor ONE®.
- 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 Netvisor ONE.
Response Payloads
All Netvisor ONE® REST APIs return a response payload with the following schema:
{{“data”:{},result:{“responseCode”:integer,”status”:”SUCCESS”|”FAILURE”,”code”:integer,”message”:string}}}
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 Netvisor ONE 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 Netvisor ONE, 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.