Integration Guides › Web Service API Reference Guide › API Generic Syntax

API Generic Syntax

To initiate an API request for an object, use a command with the following format

GET "http://ws-ip/api/v1/obj/method?arg1=<value>&arg2=<value>&vdc=<grid>"

Where:: ws-ip is the IP address used to access the 'WS_API' application
object is an API object such as app, class, and so on.
method is the action to be performed for the object such as start, stop, and so on.
arg1, arg2 are the arguments to be passed to the method
vdc is the name of the grid controller
Notes

Valued option syntax: A valued option is generally expressed in the following format:
```
<property_name>=<value>
```
The value must be URI-encoded (Uniform Resource Identifier percent-encoding), according to the rules specific to the path component of the URI. Replace any reserved character for the path field of a URI, such as percent, space and tab, equal, comma, forward slash, question mark, and single and double quotes, with its percent-encoded version %HH, where HH is the hexadecimal ASCII representation for the considered character.

Note: See RFC 3986 for details about URI encoding.

Option flag syntax: Although the CLI uses a double-hyphen or em-dash (—) as a prefix to designate an option flag (typically an option without a value), the Web Services API still uses the ampersand (&) as a prefix instead. Therefore, wherever CLI has --option, the Web Services will use &option instead. For example, if the CLI has --debug, the Web Services API will use &debug instead.
Although the descriptions of API requests for an object include all of the mandatory parameters, they only include some of the optional parameters. Optional parameters not included in this guide are described in the Command Line Shell Reference Guide.

Example:

Get the methods for object app
curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid

Example Output:

{
   "method" : [
      {
         "name" : "config"
      },
      {
         "name" : "copy"
      },
      {
         "name" : "create"
      },
      {
         "name" : "destroy"
      },
      .
      .
      .
   ]
}

Output Formats

The acceptable output formats can be XML or JSON. These can be specified in the API request.

Example:

Get the methods for object app in XML format.

curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid -H "Accept: application/xml"

Get the methods for object app in JSON format.

curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid -H "Accept: application/json"

Note: All the output in JSON is UTF8 encoded. Use a UTF8 decode to decode the UTF8 encoded output. The following is an example of a simple PHP script to decode UTF8 encoded JSON output:

<? 
$json = '{"a": "\u00e3\u0081\u0082" }'; 
$j = json_decode($json); 
echo utf8_decode($j->{'a'}); 
?>

Common Argument Types

You can use the following generic argument type that is common to many commands. When a specific argument type is referenced from any particular command description, use the following detailed information for the considered type.

<principal>

<principal> represents a persona, whether an individual or a group, of a given scope, local or global. Specify a principal according to one the following possible syntaxes:

<name>: Local user or group.
/<name>: Global user or group.
<scope>:<type>:<name>: A fully qualified principal name where <scope> is global or local, <type> is group or user, and <name> is the group or user name.

Note: A principal must be URL-encoded. For example, local:user:api@3tera.com should be passed as local%3Auser%3Aapi%403tera.com