Return values

For each request there will be an HTTP protocol return value (see RFC 2616). This way the user will know if its request has been successful or not.

Additionally, for each request there might be a JSON object (responses with a 204 return code will not have any data) which might have the following fields:

  • errors: List of errors or warnings occurred during request’s execution. A request might be successful and still have errors (warnings). If no error happened, this key won’t exist.

  • msg: List of additional information not covered in either the resource or the error list. This key won’t exist if there is none.

  • queue_token: If the request is queued, this key will contain information for querying the status of a queued request.

  • <resource>: Information/Resource asked for. Its name will depend upon the request. i.e.: create disk will return a disk key.

Success Codes

Possible return codes meaning a successful request

Code

Explanation

200

Request successful and there will be a JSON object

201

Resource created. There will be a JSON object

204

Request successful, but won’t return anything.

202

Request successfully queued, there will be a token for querying about the queued request progress, there will be also a JSON object with known data, although queued request might still fail.

Error Codes

Explanation of error codes used

Possible errors returned

Code

Explanation

400

Bad Request: Malformed syntax or a bad query. Route doesn’t exist or JSON parameters aren’t valid.

401

Unauthorized: Action requires user authentication

403

Forbidden: Authentication failure or invalid Application ID

404

Not Found: Resource not found

405

Not Allowed: Method not allowed on resource. Route does exist but it is not using the correct HTTP method (POST instead of GET, etc.)

406

Not Acceptable: Requested representation not available for the resource. In our case, header must ask for an application/json, as this is currently the only option supported.

409

Resource Conflict (PUT, PUT, DELETE): State of the resource doesn’t permit request. I.e.: disk is blocked.

412

Precondition failed (GET): Operation not completed because preconditions were not met. This will only happen if a resource depends on other and the latter is not in an acceptable state. i.e.: Deleting a vm with its disks blocked.

416

Requested Range Not Satisfiable (GET): Requested range not satisfiable. Wrong pagination request

417

Application error

500

Server Error (GET, POST, PUT): Internal server error

501

Not Implemented (POST, PUT, DELETE): Requested HTTP operation not yet implemented.

502

Bad Gateway: Backend service failure (data store failure). Api is not available.

503

Service Unavailable: Down for maintenance

Error codes classified by type of Request

Possible error codes by type of api call

Api call type

Possible error codes

Any

401, 403, 406, 500, 501, 502, 503

Unknown

400, 405

Create

400, 412

Delete

404, 409, 412

Edit

400, 404, 409, 412

Do Action (POST)

400, 404, 409, 412

Get by id

404, 416

List (GET)

400, 404, 416