Interpreting an API response

11/10/2022 Contributors

Each API request generates a response back to the client. You should examine the response to determine whether it was successful and retrieve additional data as needed.

HTTP status code

The HTTP status codes used by the ONTAP REST API are described below.

Code	Reason phrase	Description
200	OK	Indicates success for calls that do not create a new object.
201	Created	An object is successfully created. The location header in the response includes the unique identifier for the object.
202	Accepted	A background job has been started to perform the request, but has not completed yet.
400	Bad request	The request input is not recognized or is inappropriate.
401	Unauthorized	User authentication has failed.
403	Forbidden	Access is denied due to an authorization error.
404	Not found	The resource referred to in the request does not exist.
405	Method not allowed	The HTTP method in the request is not supported for the resource.
409	Conflict	An attempt to create an object failed because a different object must be created first or the requested object already exists.
500	Internal error	A general internal error occurred at the server.

Code

Reason phrase

Description

200

Indicates success for calls that do not create a new object.

201

Created

An object is successfully created. The location header in the response includes the unique identifier for the object.

202

Accepted

A background job has been started to perform the request, but has not completed yet.

400

Bad request

The request input is not recognized or is inappropriate.

401

Unauthorized

User authentication has failed.

403

Forbidden

Access is denied due to an authorization error.

404

Not found

The resource referred to in the request does not exist.

405

Method not allowed

The HTTP method in the request is not supported for the resource.

409

Conflict

An attempt to create an object failed because a different object must be created first or the requested object already exists.

500

Internal error

A general internal error occurred at the server.

Response headers

Several headers are included in the HTTP response generated by the ONTAP.

Location: When an object is created, the location header includes the complete URL to the new object including the unique identifier assigned to the object.
Content-type: This will normally be application/hal+json.

Response body

The content of the response body resulting from an API request differs based on the object, processing type, and the success or failure of the request. The response is always rendered in JSON.

Single object

A single object can be returned with a set of fields based on the request. For example, you can use GET to retrieve selected properties of a cluster using the unique identifier.
Multiple objects

Multiple objects from a resource collection can be returned. In all cases, there is a consistent format used, with num_records indicating the number of records and records containing an array of the object instances. For example, you can retrieve the nodes defined in a specific cluster.
Job object

If an API call is processed asynchronously, a Job object is returned which anchors the background task. For example, the PATCH request used to update the cluster configuration is processed asynchronously and returns a Job object.
Error object

If an error occurs, an Error object is always returned. For example, you will receive an error when attempting to change a field not defined for a cluster.
Empty JSON object

In certain cases, no data is returned and the response body includes an empty JSON object.

HAL linking

The ONTAP REST API uses HAL as the mechanism to support Hypermedia as the Engine of Application State (HATEOAS). When an object or attribute is returned that identifies a specific resource, a HAL-encoded link is also included allowing you to easily locate and determine additional details about the resource.

Errors

If an error occurs, an error object is returned in the response body.

Format

An error object has the following format:

"error": {
"message": "<string>",
"code": <integer>[,
"target": "<string>"]
}

You can use the code value to determine the general error type or category, and the message to determine the specific error. When available, the target field includes the specific user input associated with the error.

Common error codes

The common error codes are described in the following table. Specific API calls can include additional error codes.

Code		Description
1	409	An object with the same identifier already exists.
2	400	The value for a field has an invalid value or is missing, or an extra field was provided.
3	400	The operation is not supported.
4	405	An object with the specified identifier cannot be found.
6	403	Permission to perform the request is denied.
8	409	The resource is in use.