CLI to web services translation

This topic describes using the CLI to understand public web service APIs.

The command-line interface is a direct translation of the web services API to an interactive environment. This allows you to use the CLI to explore functionality with tab completion, integrated help, stronger type checking, and an indication of expected types and required fields. When trying to determine how to invoke an operation through the web services or interpret the results, it is recommended that you first learn how to do the same through the CLI, and then use the provided tools to translate that into web services call.

CLI translation to HTTP

The CLI namespace is identical to the web service URLs for each base object and operation type. The root of all web services is /resources/json/delphix. Any additional CLI context is appended to this URL, joined by slashes. For example:

delphix> database provision

Is equivalent to:

POST /resources/json/delphix/database/provision

All operations in the CLI (those that require an explicit commit command) are modeled as POST HTTP calls. This is an example of a "root operation", as they are invoked not on any particular object, but across the system as a whole. Operations that are invoked on a particular object use a URL specific to that object:

delphix> database "dexample" refresh

Is equivalent to:

POST /resources/json/delphix/database/ORACLE_DB_CONTAINER-3/refresh

While the CLI uses names to refer to objects, at the API level we use references. Persistent objects (those with a permanent unique identity) have a reference field that is used in all cases to refer to the object. This allows references to remain constant even if objects are renamed.

For the standard CRUD (create, read, update, delete) operations, the mapping is slightly different:

The DELETE operation has an optional POST form that can take complex input for clients that don't support sending a payload as part of a DELETE operation.

Tracing HTTP calls

The CLI also provides facilities to see the raw HTTP calls being made as part of any operation. To start with, viewing data in JSON format (setopt format=json) will provide an example of what the raw output looks like from the server. In its raw form, the CLI does not make any attempt to interpret the results, so references are displayed as references (and not names), and sizes are displayed as their raw numeric value.

This is helpful for scripting, but the CLI also has a mode to display the requests being sent to the server, the responses received, and the URLs used. To enable this mode, run setopt trace=true. Once you have determined how to do something through the CLI, you can use this mode as the basis for building direct integration with the raw HTTP APIs.

delphix group> setopt trace=true
delphix group> create
delphix group create *> set name=example
delphix group create *> set description="this is an example"
delphix group create *> commit
=== POST /resources/json/delphix/group ===
{
    "type": "Group",
    "name": "example",
    "description": "this is an example"
}
=== RESPONSE ===
{
    "status": "OK",
    "result": "GROUP-3",
    "action": "ACTION-37",
    "job": null
}
=== END ===
    GROUP-3
delphix group> "example"
delphix group "example"> delete
=== GET /resources/json/delphix/group/GROUP-3 ===
=== RESPONSE ===
{
    "status": "OK",
    "result": {
        "type": "Group",
        "reference": "GROUP-3",
        "namespace": null,
        "name": "example",
        "description": "this is an example"
    },
    "action": null,
    "job": null
}
=== END ===
delphix group "example" delete *> commit
=== POST /resources/json/delphix/group/GROUP-3/delete ===
{}
=== RESPONSE ===
{
    "status": "OK",
    "result": "",
    "action": "ACTION-38",
    "job": null
}
=== END ===
delphix group>

When using trace mode within the context of a specific object, we refresh the contents of the object before executing each command. This results in the GET request before the delete command in the above example.