Web service protocol

This topic describes an overview of the web service API and available facilities.

Introduction

The Delphix Engine provides a set of public stable web service APIs (application programming interfaces). The web services form the basis upon with the GUI and CLI are built, and are designed to be public and stable. This guide covers the basic operation of the protocol, concepts, and considerations when building layered infrastructure. It is not a reference for all available APIs. For more information on available APIs, go to the '/api' URL of a Delphix appliance, which will provide a complete reference of all available APIs for the version of Delphix running on that system.

CODE


http://<server>/api

The CLI is a thin veneer over the web services. If you are new to the web services, it is recommended you first test out operations with the CLI, and use the setopt trace=true option to dump the raw data being sent and received to see the API in action.

Protocol operation

The Delphix web services are a RESTful API with loose CRUD semantics using JSON encoding.

The following HTTP methods are supported:

GET - Retrieve data from the server where complex input is not needed. All GET requests are guaranteed to be read-only, but not all read-only requests are required to use GET. Simple input (strings,number, boolean values) can be passed as query parameters.
POST - Issue a read/write operation, or make a read-only call that requires complex input. The optional body of the call is expressed as JSON.
DELETE - Delete an object on the system. For languages that don't provide a native wrapper for DELETE, or for delete operations with optional input, all delete operations can also be invoked as POST to the same URL with /delete appended to it.

Regardless of the operation, the result is returned as a JSON encoded result, the contents of which are covered below. For example, the following invocation of curl demonstrates establishing a new Session (pretty-printing the result):

CODE


$ curl -s -X POST -k --data @- http://delphix-server/resources/json/delphix/session \   -c ~/cookies.txt -H "Content-Type: application/json" <<EOF{   "type": "APISession",   "version": {       "type": "APIVersion",       "major": 1,       "minor": 4,       "micro": 3   }}EOF{   "status":"OK",   "result": {       "type":"APISession",       "version": {           "type": "APIVersion",           "major": 1,           "minor": 4,           "micro": 3       },       "locale": "en_US",       "client": null   },   "job": null}EOF

NOTE: It is generally recommended to set the API session version to the highest level supported by your Delphix Engine.

Session establishment

Login involves establishing a session and then authenticating to the Delphix Engine. Only authenticated users can access web APIs. Each user must establish a session prior to making any other API calls. This is done by sending a Session object to the URL /resources/json/delphix/session. This session object will specify the APIVersion to use for communication between the client and server. If the server doesn't support the version requested due to an incompatible change reflected in the API major version number, an error will be returned.

The resulting session object encodes the native server version, which can be different than the version requested by the client. If the server is running a more recent but compatible version, any translation of input and output to the native version is handled automatically. More information on versioning can be found in the documentation for the APIVersion object within the API reference on a Delphix system. If the client supports multiple versions, the appropriate type can be negotiated by trying to establish a session with each major version supported and then inspecting the version returned.

The session will also return an identifier through browser cookies that can be reused in subsequent calls to use the same session credentials and state without having to re-authenticate. The format of this cookie is private to the server and may change at any point. Sessions do not persist across a server restart or reboot. The mechanism by which this cookie is preserved and sent with subsequent requests is client-specific. The following demonstrates invoking the session login API call using curl and storing the cookies in the file ~/cookies.txt for later use:

CODE


$ curl -s -X POST -k --data @- http://delphix-server/resources/json/delphix/session \   -c ~/cookies.txt -H "Content-Type: application/json" <<EOF{   "type": "APISession",   "version": {       "type": "APIVersion",       "major": 1,       "minor": 4,       "micro": 3   }}EOF{   "status":"OK",   "result": {       "type":"APISession",       "version": {           "type": "APIVersion",           "major": 1,           "minor": 4,           "micro": 3       },       "locale": "en_US",       "client": null   },   "job": null}EOF

Authentication

Once the session has been established, the next step is to authenticate to the server by executing the LoginRequest API. Unauthenticated sessions are prohibited from making any API calls other than this login request. The username can be either a system user or domain user, and the backend will authenticate using the appropriate method. This example illustrates logging in via curl using cookies created when the session was established:

CODE


$ curl -s -X POST -k --data @- http://delphix-server/resources/json/delphix/login \-b cookies.txt -c cookies2.txt -H "Content-Type: application/json" <<EOF{"type": "LoginRequest","username": "delphix_user","password": "delphix_pass","target": "DOMAIN"}EOF

The new cookie (cookie2.txt) will need to be used in subsequent API requests. The login API currently only supports authentication by a password. There is no way to authenticate using any shared key or alternate authentication strategy.