API basics

11/05/2021 Contributors

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

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.

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:

GET requests are used for read-only requests.
POST requests are used to create and update objects, and also for read requests that might have security implications.
DELETE requests are typically used to remove an object from management, remove an object entirely, or to reset the state of the object.

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:

HTTP status code — Indicates whether the request was successful.
Optional response body — Usually provides a JSON body representing the state of the resource or a body providing more details on the nature of a failure.

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

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.

400 Bad Request

Indicates that the JSON body provided in the request is not valid.

401 Unauthorized

Indicates that an authentication failure has occurred. Either no credentials were provided, or the username or password was invalid.

403 Forbidden

An authorization failure, which indicates that the authenticated user does not have permission to access the requested endpoint.

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.

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.

429 Too Many Requests

Indicates that a request limit was exceeded and should be retried at a later time.

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 NetApp Webservices samples.