API responses

API responses provide a response code from the IBM Spectrum Scale™ management API server and a return code and optional return message from IBM Spectrum Scale.

Return codes and messages

A return code and an optional return message from IBM Spectrum 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 Spectrum Scale processed the request successfully:

  "status": {
    "message": "", 
    "code": 200
  },

A response code from the IBM Spectrum Scale management API server describes the result of the API request. The following table lists the response codes:

Table 1. 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 will continue 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 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 Spectrum Scale management API responses always include some data in JSON format. The status structure with a return code and an optional return message is always present. 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, square brackets [ ] 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"
}