Delphix RESTFul APIs command line basics

Authentication

RESTFul APIs require authentication. Just plugging the URL into a web browser or running an operating system cURL command will return an authentication/login required error message.

Command line:

curl http://172.16.160.195/resources/json/delphix/environment

Response:

Copy 
<!DOCTYPE html>
<html>
<head>
<title>Apache Tomcat/8.0.29 - Error report</title>
<style type="text/css">
H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} 
H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} 
H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} 
BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} 
B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} 
P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;} 
A {color : black;} 
A.name {color : black;} 
.line {height: 1px; background-color: #525D76; border: none;}
</style> 
</head>
<body>
<h1>HTTP Status 403 - Use /resources/json/delphix/login to log in first</h1>
<div class="line"></div>
<p><b>type</b> Status report</p>
<p><b>message</b> <u>Use /resources/json/delphix/login to log in first</u></p>
<p><b>description</b> <u>Access to the specified resource has been forbidden.</u></p>
<hr class="line">
<h3>Apache Tomcat/8.0.29</h3>
</body>
</html>

The authentication process requires you to establish a session first.

The example within this section illustrates the session/login and subsequent API calls with cURL using cookies created when the session was established.

Session

API version information

When programming for compatibility, the API version number is very important. Please be aware of the differences between versions for enterprise applications. For example, if you specify a 1.11.6 version, ONLY the available calls and functionality for that version will be used, and it will only be operational on Delphix Engine versions that support that version.

The session uses the –c for the cookie creation, the login uses the -b for the exiting cookie created by the session, and -c to create a new cookie, the other commands use the –b for using the existing cookie created by the login.

  1. From the Unix/Linux command line:

    Copy 
    $ 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": 11,       
          "micro": 6   
        }
      }
      EOF

  2. Returned to the command line are the results (added linefeeds for readability):

    Copy 
    {   
      "status": "OK",   
      "result": {       
        "type": "APISession",       
        "version": {           
          "type": "APIVersion",           
          "major": 1,           
          "minor": 11,           
          "micro": 6       
        },       
        "locale": "en_US",       
        "client": null   
      },   
      "job": null
    }

Login

Once you have established the session, the next step is to authenticate to the server by executing the Login Request 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; the backend will authenticate using the appropriate method.

The session uses the –c for the cookie creation, the login uses the -b for the exiting cookie created by the session, and -c to create a new cookie, the other commands use the –b for using the existing cookie created by the login.

  1. From the Unix/Linux command line:

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

  2. Returned to the command line are the results (added linefeeds for readability):

    Copy 
    {"status":"OK","result":"USER-2","job":null,"action":null}

Sample Delphix API call

With a successful authentication (session, login, and saved cookie), calls to the Delphix Engine can now be made to perform the desired functionality.

The session uses the –c for the cookie creation, the login uses the -b for the exiting cookie created by the session, and -c to create a new cookie, the other commands use the –b for using the existing cookie created by the login.

  1. Create a session, login, and get the existing environments defined within the Delphix Engine:

    Copy 
    curl -s -X POST -k --data @- http://172.16.160.195/resources/json/delphix/session \
      -c ~/cookies.txt -H "Content-Type: application/json" 
      <<EOF
      {    
        "type": "APISession",    
        "version": {        
          "type": "APIVersion",        
          "major": 1,        
          "minor": 7,        
          "micro": 0      
        }    
      }
      EOF
    Copy 
    curl -s -X POST -k --data @- http://172.16.160.195/resources/json/delphix/login \
      -b ~/cookies.txt -c ~/cookies.txt -H "Content-Type: application/json" 
      <<EOF
      {    
        "type": "LoginRequest",    
        "username": "admin",    
        "password": "delphix"  
      }
      EOF
    Copy 
    curl -X GET -k http://172.16.160.195/resources/json/delphix/environment \
      -b ~/cookies.txt -H "Content-Type: application/json"

  2. Returned to the command line are the results (added linefeeds for readability):

    Copy 
    {
      "type": "ListResult",
      "status": "OK",
      "result": [
        {
          "type": "WindowsHostEnvironment",
          "reference": "WINDOWS_HOST_ENVIRONMENT1",
          "namespace": null,
          "name": "Window Target",
          "description": "",
          "primaryUser": "HOST_USER-1",
          "enabled": false,
          "host": "WINDOWS_HOST1",
          "proxy": null
        },
        {
          "type": "UnixHostEnvironment",
          "reference": "UNIX_HOST_ENVIRONMENT-3",
          "namespace": null,
          "name": "Oracle Target",
          "description": "",
          "primaryUser": "HOST_USER-3",
          "enabled": true,
          "host": "UNIX_HOST-3",
          "aseHostEnvironmentParameters": null
        }
      ],
      "job": null,
      "action": null,
      "total": 2,
      "overflow": false
    }

Windows PowerShell authentication example

See the PowerShell section below if cURL is not yet available on your operating system.

These commands work on Windows Command Prompt with the respective JSON files: session.json and login.json

Filename: session.json

Copy 
{
    "type": "APISession",
    "version": {
        "type": "APIVersion",
        "major": 1,
        "minor": 7,
        "micro": 0
    }
}

Filename: login.json

Copy 
{"type": "LoginRequest","username": "admin","password": "delphix"}

(In Powershell you use curl.exe or modify the default alias):

Copy 
curl.exe --insecure -c cookies.txt -sX POST -H "Content-Type: application/json" -d "@session.json" http://172.16.160.195/resources/json/delphix/session
curl.exe --insecure -b cookies.txt -c cookies.txt -sX POST -H "Content-Type: application/json" -d "@login.json" http://172.16.160.195/resources/json/delphix/login
curl.exe --insecure -b cookies.txt -sX GET -H "Content-Type: application/json" -k http://172.16.160.195/resources/json/delphix/system

Putt the commands in a Powershell script:

  1. Filename: auth1.ps1

    Copy 
    <#Filename: auth.ps1Description: Delphix Powershell Sample Authentication Script ...Date: 2016-08-02Author: Bitt...#>

  2. Variables

    Copy 
    $nl = [Environment]::NewLine$BaseURL = "http://172.16.160.195/resources/json/delphix"$cookie = "cookies.txt"

  3. Session JSON Data

    Copy 
    write-output "${nl}Creating session.json file ..."
    $json = @"
    {
        "type": "APISession",
        "version": {
            "type": "APIVersion",
            "major": 1,
            "minor": 11,
            "micro": 6
        }
    }"

  4. Output File using UTF8 encoding

    Copy 
    write-output $json | Out-File "session.json" -encoding utf8

  5. Delphix cURL Session API

    Copy 
    write-output "${nl}Calling Session API ...${nl}"
    $results = (curl.exe --insecure -c "$cookie" -sX POST -H "Content-Type: application/json" -d "@session.json" -k $BaseURL/session)
    write-output "Session API Results: ${results}"

  6. Login JSON Data

    Copy 
    write-output "${nl}Creating login.json file ..."
    $user = "admin"
    $pass = "delphix"
    $json = @"
    {
        "type": "LoginRequest",
        "username": "${user}",
        "password": "${pass}"
    }
    "@

  7. Output File using UTF8 encoding

    Copy 
    write-output $json | Out-File "login.json" -encoding utf8

  8. Delphix cURL Login API

    Copy 
    write-output "${nl}Calling Login API ...${nl}"
    $results = (curl.exe --insecure -b "$cookie" -c "$cookie" -sX POST -H "Content-Type: application/json" -d "@login.json" -k $BaseURL/login)
    write-output "Login API Results: ${results}"

  9. Delphix cURL system API

    Copy 
    write-output "${nl}Calling System API ...${nl}"
    $results = (curl.exe --insecure -b "$cookie" -sX GET -H "Content-Type: application/json" -k $BaseURL/system)
    write-output "System API Results: ${results}"

  10. The end is near ...

    Copy 
    echo "${nl}Done ...${nl}"exit;

  11. Sample Powershell Script output:

    Copy 
    PS> . .\auth.ps1
    Creating session.json file ...
    Calling Session API ...
    Session API Results:
    {
      "type": "OKResult",
      "status": "OK",
      "result": {
        "type": "APISession",
        "version": {
          "type": "APIVersion",
          "major": 1,
          "minor": 7,
          "micro": 0
        },
        "locale": null,
        "client": null
      },
      "job": null,
      "action": null
    }
    Creating login.json file ...
    Calling Login API ...
    Login API Results: 
    {
      "type": "OKResult",
      "status": "OK",
      "result": "USER2",
      "job": null,
      "action": null
    }
    Calling System API ...
    System API Results: 
    {
      "type": "OKResult",
      "status": "OK",
      "result": {
        "type": "SystemInfo",
        "productType": "standard",
        "productName": "Delphix Engine",
        "buildTitle": "Delphix Engine 5.1.1.0",
        "buildTimestamp": "20160721T07:23:41.000Z",
        "buildVersion": {
          "type": "VersionInfo",
          "major": 5,
          "minor": 1,
          "micro": 1,
          "patch": 0
        },
        "configured": true,
        "enabledFeatures": [
          "XPP",
          "MSSQLHOOKS"
        ],
        "apiVersion": {
          "type": "APIVersion",
          "major": 1,
          "minor": 8,
          "micro": 0
        },
        "banner": null,
        "locals": [
          "enUS"
        ],
        "currentLocale": "enUS",
        "hostname": "Delphix5110HWv8",
        "sshPublicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDOsrp7Aj6hFQh9yBq7273B+qtPKmCu1B18nPvr08yjt/IZeM4qKk7caxExQS9rpfU8AWoT7e8ESV7NkBmUzOHrHnLsuJtxPqeYoqeMubVxYjJuxlH368sZuYsnB04KM0mi39e15lxVGvxQk9tyMpl7gs7cXRz1k6puncyiczU/axGq7ALHU2uyQoVmlPasuHJbq23d21VAYLuscbtgpZLAFlR8eQH5Xqaa0RT+aQJ6B1ihZ7S0ZN914M2gZHHNYcSGDWZHwUnBGttnxx1ofRcyN4/qwT5iHq5kjApjSaNgSAU0ExqDHiqgTq0wttf5nltCqGMTFR7XY38HiNq++atDroot@Delphix5110HWv8\n",
        "memorySize": 8.58107904E9,
        "platform": "VMware with BIOS date 05/20/2014",
        "uuid": "564d7e1df4cb-f91098fd348d74817683",
        "processors": [
          {
            "type": "CPUInfo",
            "speed": 2.5E9,
            "cores": 1
          }
        ],
        "storageUsed": 2.158171648E9,
        "storageTotal": 2.0673724416E10,
        "installationTime": "2016-07-27T13:28:46.000Z"
      },
      "job": null,
      "action": null
    }
    Done ...
    PS>