API responses

API responses provide a response code from the IBM Storage Scale management API server and a return code and a non-mandatory return message from IBM Storage Scale.

Return codes and messages

A return code and an optional return message from IBM Storage Scale are stored in JSON format in a status structure at the end of any returned data. A return code of 0 indicates that IBM Storage Scale processed the request successfully:
  "status": {
    "message": "", 
    "code": 200
  },
A response code from the IBM Storage Scale management API server describes the result of the API request. The following table lists the response codes.
Table 1. Response codes. A four-column table that describes the response codes.
Description Code Client retry Return code
Success 20x None
200 - Success (GET or PUT).    
201 - New resource created (POST).
202 - Request accepted (long-running command).    
204 - No content (DELETE).
Client error 4xx No, the command continues to fail.
400 - Invalid request (format error in request data)
401 - Unauthorized request (wrong credentials).  
403 - Resource not accessible.
404 - Resource not found (wrong URL).  
405 - Method that is not supported for this resource.
Server error 5xx Yes, in most cases
500 - Internal server error, retry (system problem)
503 - Service not available (the server is busy with
other requests or is down)

Data in REST API responses

IBM Storage Scale management API responses always include some data in JSON format. The status structure with a return code and with a return message is always present. The return message is not mandatory and might not be displayed with the code. See the status structure at the end of the following JSON example. Also, GET methods return the requested information in JSON format. The following example is from a response to a request to GET information about CES addresses. In JSON, the parenthesis [ ] indicate an array. The following example contains an array that is named cesaddresses that contains two elements, each of which describes one CES address.
{
  "cesaddresses": [
     {
      "cesNode": 1,
      "attributes": "",
      "cesAddress": "198.51.100.10",
      "cesGroup": "",
     }
    },
    {
      "cesNode": 2,
      "attributes": "",
      "cesAddress": "198.51.100.14",
      "cesGroup": "",
      }
    }    
  ]
  "status": {
    "message": "", 
    "code": 200
  }
}

Response headers

The same header types appear in all responses from the REST API server. The content type must be application/json. The following set of response headers is typical:
{
 HTTP/1.1 200 OK
 X-Frame-Options: SAMEORIGIN
 Content-Type: application/json
 Content-Language: en-US
 Content-Length: 210
 Set-Cookie:
      LtpaToken2=yyYwMkAHceggOe74hZhsqf5iCU9r2nl9QBGO9nH7uPm3Mt/vpQfVEHuhwRIWKfq1fi1t8EVn6sZJx7
      +6EpVvUqxqs9PdmIXX28DzU/wwQFxGIMA5a2AuNAFYmZ7lFWqYEEhWq5tx0oQMBHQOL7AbkyR6TUq+F1wzvuZnTe1
      cwu0AYmwZr6WrWdLDj8ZMJ22k95s2PmLbmNMsuSEeSbUFmc1nZdYueieRBgL7QgokS9Ol4lX2gN8YSwWxxljfzCwsed
      MsdYvhawLhYJNA3IkOFnFVJpeopLP4EQtcSdMPXzpX+AQHn/0XQdd6iaWfHppt;
      Path=/; HttpOnly
 Set-Cookie: JSESSIONID=0000SRpFCu8e03i3WXhDyJS2qnn:8bf7532d-fb68-4d4b-90fc-4aa4e3deefd5;
      Path=/; Secure; HttpOnly
 Date: Thu, 16 Feb 2017 15:14:52 GMT
 Expires: Thu, 01 Dec 1994 16:00:00 GMT
 Cache-Control: no-cache="set-cookie, set-cookie2"
}