Go to main content

Remote Administration Daemon Developer's Guide

Exit Print View

Updated: May 2019
 
 

REST Responses

All REST responses have the following basic JSON structure:

{
            "status":    "success" ||
            "object-specific error" ||
            "not found error" ...
            "payload":    null || <resource specific>
}

HTTP Status Codes and REST

    Because REST requests are made over HTTP, the client receives HTTP status codes in a response. Some of the common HTTP return codes and their corresponding meaning in the context of RAD are as follows:

  • 200 OK – Request succeeded.

  • 201 Created – Request succeeded and a new resource is created.

  • 204 No Content – Request succeeded but the server did not return a message body.

  • 400 Bad Request – Request did not succeed, possibly because of a data-type mismatch or a illegal access.

  • 401 Unauthorized – Insufficient privileges.

  • 404 Not found – Specified resource was not found.

Error Responses to RAD Request

For non-fatal errors, the server responds with information about the issue. The basic JSON structure of an error response is as follows:

{
         "status": text-of-the-RAD error,
         "payload": payload
}

In case of a HTTP 503 error, the value is defined and returned by the RAD module that is mentioned in the request. For all other errors, the payload value has the following format:

{
     "Message": description-of-error,

     "HTTP Method": ("HEAD"|"GET"|"POST"|"PUT"|"DELETE"),

     "URI": full-URI-with-all-query-parameters,

     "RAD Operation": ("INVOKE"|"GETATTR"|"SETATTR"|"LOOKUP"|"LIST"|null),

     "Request payload": { Arguments provided by the client },

     "Method": name of a method for INVOKE operation,

     "Attribute": name of an attribute/property for GETATTR, SETATTR ops,

     "Pattern": URI translated to RAD list pattern for LIST operation,

     "Name": URI translated to RAD name for LOOKUP operation,

     "Object": { URI translated to RAD object (any operation but LIST)

     "Name": name of a module, also known as domain

     "Interface": name of the interface,
     },

     "Reference": RAD reference ID found in the special _rad_reference URIs,

     "Version": { Module version as found in the URI

     "Major": int,

     "Minor": int
     }
   }

Information that is not provided in the request or could not be decoded from the request is included in the response as a JSON null.

Some of the examples of possible error messages are as follows:

Decoding request body as JSON failed: too big integer near '18446744073709551615'
Invalid (array) argument 'arg'='[true,false,true,false]' - element [0]
     - integer out of bounds (-2147483648, 2147483647)