API basics

In the Web Services API, HTTP communications involve a request-response cycle.

URL elements in requests

Regardless of the programming language or tool used, each call to the Web Services API has a similar structure, with a URL, HTTP verb, and an Accept header.

All requests include a URL, as in the following example, and contain the elements described in the table.

https://webservices.name.com:8443/devmgr/v2/storage-systems

Area Description

HTTP transport

https://

The Web Services Proxy enables the use of HTTP or HTTPS.

The embedded Web Services requires HTTPS for security reasons.

Base URL and port

webservices.name.com:8443

Each request must be correctly routed to an active instance of Web Services. The FQDN (fully qualified domain name) or the IP address of the instance is required, along with the listening port. By default, Web Services communicates over port 8080 (for HTTP) and port 8443 (for HTTPS).

For the Web Services Proxy, both ports can be changed during the proxy installation or in the wsconfig.xml file. Port contention is common on data center hosts running various management applications.

For the embedded Web Services, the port on the controller cannot be changed; it defaults to port 8443 for secure connections.

API path

devmgr/v2/storage-systems

A request is made to a specific REST resource or endpoint within the Web Services API. Most endpoints are in the form of:

devmgr/v2/<resource>/[id]

The API path consists of three parts:
  • devmgr (Device Manager) is the namespace of the Web Services API.
  • V2 denotes the version of the API that you are accessing. You can also use utils to access login endpoints.
  • storage-systems is a category within the documentation.

Supported HTTP verbs

Supported HTTP verbs include GET, POST, and DELETE:

Note: Currently, the Web Services API does not support PUT or PATCH. Instead, you can use POST to provide the typical functionality for these verbs.

Accept headers

When returning a request body, Web Services returns the data in JSON format (unless otherwise specified). Certain clients default to requesting “text/html” or something similar. In these cases, the API responds with an HTTP code 406, denoting that it cannot provide data in this format. As a best practice, you should define the Accept header as “application/json” for any cases in which you expect JSON as the response type. In other cases where a response body is not returned (for example, DELETE), providing the Accept header does not cause any unintended effects.

Responses

When a request is made to the API, a response returns two critical pieces of information:

You must check the status code and the content-type header to determine what the resulting response body looks like. For HTTP status codes 200-203 and 422, Web Services returns a JSON body with the response. For other HTTP status codes, Web Services generally does not return an additional JSON body, either because the specification does not allow it (204) or because the status is self-explanatory. The table lists common HTTP status codes and definitions. It also indicates whether information associated with each HTTP code is returned in a JSON body.

HTTP status code Description JSON body
200 OK Denotes a successful response. Yes
201 Created Indicates that an object was created. This code is used in a few rare cases instead of a 200 status. Yes
202 Accepted Indicates that the request is accepted for processing as an asynchronous request, but you must make a subsequent request to get the actual result. Yes
203 Non-Authoritative Information Similar to a 200 response, but Web Services cannot guarantee that the data is up-to-date (for example, only cached data is available at this time). Yes
204 No Content Indicates a successful operation, but there is no response body. No
400 Bad Request Indicates that the JSON body provided in the request is not valid. No
401 Unauthorized Indicates that an authentication failure has occurred. Either no credentials were provided, or the username or password was invalid. No
403 Forbidden An authorization failure, which indicates that the authenticated user does not have permission to access the requested endpoint. No
404 Not Found Indicates that the requested resource could not be located. This code is valid for nonexistent APIs or nonexistent resources requested by the identifier. No
422 Unprocessable Entity Indicates the request is generally well-formed, but either the input parameters are invalid, or the state of the storage system does not allow Web Services to satisfy the request. Yes
424 Failed Dependency Used in the Web Services Proxy to indicate that the requested storage system is currently inaccessible. Therefore, Web Services cannot satisfy the request. No
429 Too Many Requests Indicates that a request limit was exceeded and should be retried at a later time. No

Sample scripts

GitHub contains a repository for the collection and organization of sample scripts illustrating the use of the NetApp SANtricity Web Services API. To access the repository, see: https://github.com/NetApp/webservices-samples.