Send Requests

Request and Response JSON formats while accessing REST API

The HTTP requests and responses use JSON in HTTP content for IO handling.

JSON Payload

A general HTTP request payload (login request is different) follows the following structure:

{
  "command" : "operation/command name"
  "arguments" : [
    {"argumentName":"value"},
    {"argumentName":"value"},
    {"argumentName":"value"}
  ]
}

The command field maps to a single command or a command with sub commands in the admin CLI. The arguments field passes the command arguments and values to the command service in a JSON array structure.

Below is an example of a JSON payload for the deploy-sn command:

{
  "command" : "deploy-sn"
  "arguments" : [
    {"zn":"zn1"},
    {"host": "localhost"},
    {"port":5000}
  ]
}

The array value of arguments is a JSON object. Each JSON object has only one entry with name/value pair. The entry name is the argument name of a command. The entry value is the command argument value. The argument name/value pair in the arguments field must be in the same serial order as the admin CLI command.

The entry name must follow the pattern below:

argumentNameWithMutiplePart

This name is converted to admin CLI argument name:

-argument-name-with-multiple-part

The argument value can be in string or boolean. For example:

{"zn": "stringValueOfZnId"}
{"port": "5000"}
{"useArbiter": true}

A boolean argument value is parsed in command line if it is set to true. In the above example, the {"useArbiter": true}, is parsed to -use-arbiter in command line.

Response

The JSON payload in HTTP response follows the following structure to indicate the result.

The format of the response returned from every API call is as shown below:

{
   operation : string   
   returnCode : string
   description : string 
   returnValue : object
}

{
  "operation" : "command name or specific operation name"
  "returnCode" : "error code range from 5000 to 5500 to indicate failure, 5000 is successful"
  "description" : "description of the result, it could be text result of the command output if information need to be read manually by administrator"
  "returnValue" : "Useful information structured in JSON format to allow application to handle the result automatically"
}

For example :

{
    "operation":"Command related operation",
    "returnCode":"Error code to indicate the command result, 5000 infers plan success, 5100 infers illegal command, 5200 - 5500 infers connection/resource/internal problem of executing plan.",
    "description":"Textual output of the command",
    "returnValue":"Valuable information returned by the command execution in JSON object format"
}

All admin web service API return JSON in HTTP response payload. The resulting JSON payload is mapped to the JSON output of the admin CLI command and the result is the same as using the -json option in the admin CLI command.