Professional Documents
Culture Documents
Version 6.3
EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without
notice.
The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect
to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular
purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license.
EMC2, EMC, and the EMC logo are registered trademarks or trademarks of EMC Corporation in the United States and other countries.
All other trademarks used herein are the property of their respective owners.
The management system governing the design and development of this product is ISO 9001:2008 certified.
For the most up-to-date support, product, and licensing information to EMC Online Support at http://support.EMC.com.
For technical support, go to EMC Online Support and select Support. There are several options, including one to create a service
request. To create a service request you must have a valid support agreement. Contact your EMC sales representative about obtaining
a valid support agreement or with questions about your account.
Your suggestions will help us to improve the accuracy, organization, and overall quality of user publications. To provide feedback,
please email DPAD.Doc.Feedback@emc.com.
Revision history
The following table presents the revision history of this document:
01 February 13, 2017 First release of this document for DPA 6.3
TABLE OF CONTENTS
OVERVIEW
REST (Representational State Transfer) is a simple stateless architecture that generally runs over HTTP. The REST
style emphasizes that interactions between clients and services are enhanced by having a limited number of
operations. Flexibility is provided by assigning resources their own URIs (unique universal resource indicators).
Because each operation (GET, POST, PUT and DELETE) has a specific meaning, REST avoids ambiguity.
The REST API is active by default in all instances, starting with the DPA 6.0 release.
RESTful web services offer administrators several advantages, including:
• Support for different HTTP methods to perform different actions
• Detailed response codes and header information
• Pagination support for large data sets
1
Engineers’ Guide to Using DPA REST API 6.3
The DPA REST API is a RESTful interface that allows programmers to access information that has been collected,
stored and managed by DPA. By using the REST API to retrieve data discovered and calculated by DPA, application
developers can build their own applications and mashups that leverage this information.
The REST API provides a more robust and expansive API with increased functionality that allows programmers to
extract DPA data via any tool or programming language that supports RESTful API calls.
SUPPORTED METHODS
The following methods conform to the REST standard and are available in DPA 6.x:
GET
POST
PUT
DELETE
Note that not all DPA resources have all methods available. Please consult the online reference
https://localhost:9002/Help/rest-api-help.html for details.
HEADERS
Each of the methods listed above can be overridden by setting the X-http-method-override header. The
Accept and Content-Type request headers are required for proper data formatting. These request headers
have the following valid values:
POST, PUT, PATCH, and DELETE operations require you to provide both headers. The GET operation requires only
the Accept header. Failing to provide the required headers results in a 400 Bad Request error.
The data collected by DPA, or calculated, is grouped internally as resources. The DPA REST API consists of a robust
set of URIs used to access these different resources within DPA.
The URI syntax for each of these applications is as follows:
https://{server name}:{port}/dpa-api/{resource}
The DPA server name is deployment-specific and the resource is the resource identity name of information to be
accessed. For example:
2
Engineers’ Guide to Using DPA REST API 6.3
https://dpaserver.emc.com:9002/dpa-api/license
Note: A DPA administrative level password will be required to get the response.
<license lastModified="2015-07-08T11:41:45.41-04:00">
<id>fc51fe08-0e5a-40f4-9c3a-917e84e0eb21</id>
<name>RecoverPoint Metering</name>
<code>DPA_RECOVERPOINT_BUNDLE</code>
<instances>20</instances>
<expiry>0</expiry>
<featureSet>0</featureSet>
</license>
</licenses>
3
Engineers’ Guide to Using DPA REST API 6.3
With the installation of the DPA application node a REST client is provided that can be executed from the
command line. This CLI activated tool supports:
• Definition of requests in an XML file that be executed via the command line
• Adhoc requests using command line parameters
• Overriding predefined XML file commands via command line parameters
The DPA REST client can be activated on the command line by typing:
or in short form:
configuration.xml example
<configuration>
<api>
<rest>
<shortcut>server-status</shortcut>
<restDescriptor>
4
Engineers’ Guide to Using DPA REST API 6.3
<host>https://localhost:9002</host>
<path>dpa-api/server/status</path>
<method>GET</method>
<login>administrator</login>
<headers>
<header>
<key>Content-Type</key>
<value>application/vnd.emc.apollo-v1+xml</value>
</header>
<header>
<key>Accept</key>
<value>*/*</value>
</header>
</headers>
</restDescriptor>
</rest>
<rest>
<shortcut>agent-configuration</shortcut>
<restDescriptor>
<path>dpa-api/agents/b082fd45-dc15-4c62-8869-3b8c523e50a0/settings</path>
<method>GET</method>
<login>administrator</login>
<headers>
<header>
<key>Content-Type</key>
<value>application/vnd.emc.apollo-v1+xml</value>
</header>
<header>
<key>Accept</key>
<value>*/*</value>
</header>
</headers>
</restDescriptor>
</rest>
</api>
</configuration>
Note: The server-status component of this example is defined by default within the executive ear file
config/configuration.xml. If it is required when using a customer-created configuration.xml file it
should be defined in this file as per the above example.
ALLOWED TAGS
• shortcut - the name of REST descriptor which is used for executing predefined request
• restDescriptor - the REST descriptor to execute
o host - host where DPA is installed with a port
o path - REST API path
o method - method of HTTP request [GET, DELETE, PUT, POST]
o body – (body of request) link to a file with body (xml file for instance) or escaped XML text. This is
Valid only for PUT and POST requests.
o login – DPA user name for authorization
o headers - list of headers
key - header name
5
Engineers’ Guide to Using DPA REST API 6.3
Example
dpa app query -api server-status -a
• -api server-status - point to predefined shortcut named "server status"
• -a - flag for DPA authorization
===============================================================
=====================A B R A C A D A B R A=====================
======================A B R A C A D A B R======================
=======================A B R A C A D A B=======================
========================A B R A C A D A========================
=========================A B R A C A D=========================
==========================A B R A C A==========================
===========================A B R A C===========================
============================A B R A============================
=============================A B R=============================
==============================A B==============================
===============================A===============================
Interactive authorize on DPA. DPA user password:
================== COMMAND LINE PARAMETERS: ===================
api
server-status
outputType
XML
authorization required
true
=================== CONFIG XML PARAMETERS: ====================
[server-status]
host
https://localhost:9002
path
dpa-api/server/status
method
GET
header
Content-Type : application/vnd.emc.apollo-v1+xml
login
administrator
==================== REQUEST PARAMETERS: ======================
host
https://localhost:9002
path
dpa-api/server/status
method
GET
header
Authorization : BASIC YWRtaW5pc3RyYXRvcjphZG1pbmlzdHJhdG9y
Content-Type : application/vnd.emc.apollo-v1+xml
6
Engineers’ Guide to Using DPA REST API 6.3
login
administrator
======================== REQUEST RESULT ========================
status code: 200
================================================================
<serverStatus>
<product> Data Protection Advisor</product>
<status>STARTED</status>
<version>
<major>6</major>
<minor>2</minor>
<maintenance>2</maintenance>
<build>96949</build>
</version>
<operatingSystem>
<family>WINDOWS</family>
<version>6.1</version>
<processorType>amd64</processorType>
</operatingSystem>
<user version="1" lastModified="2015-07-08T16:34:13.403-07:00" resource-version="1" system="true" hidden="false">
<id>46c9a9d5-a645-4dcb-b288-3d30ff930ad7</id>
<displayName>Administrator</displayName>
<logonName>administrator</logonName>
<authenticationType>PASSWORD</authenticationType>
<userRole version="1" lastModified="2015-07-08T16:31:42.585-07:00" resource-version="1" system="true" hidden="false">
<id>36ad0bd5-dfa6-47c3-bf7b-a48140c93a8f</id>
<name>Administrator</name>
<description>Administrators have complete and unrestricted access to the application</description>
<permissions>
<permission name="apollo.analysispolicy.readwrite">true</permission>
<permission name="apollo.activereports.read">true</permission>
<permission name="apollo.alerts.read">true</permission>
<permission name="apollo.systemsettings.read">true</permission>
<permission name="apollo.activereports.readwrite">true</permission>
<permission name="apollo.chargebackpolicy.readwrite">true</permission>
<permission name="apollo.reporttemplate.readwrite">true</permission>
<permission name="apollo.replicationanalysis.read">true</permission>
<permission name="apollo.inventory.readwrite">true</permission>
<permission name="apollo.analysispolicy.read">true</permission>
<permission name="apollo.register.agent">true</permission>
<permission name="apollo.reporttemplate.read">true</permission>
<permission name="apollo.systemsettings.readwrite">true</permission>
<permission name="apollo.dashboard.readwrite">true</permission>
<permission name="import.read">true</permission>
<permission name="apollo.datacollectionpolicy.readwrite">true</permission>
<permission name="apollo.chargebackpolicy.read">true</permission>
<permission name="apollo.dashboard.read">true</permission>
<permission name="apollo.permissions.list">true</permission>
<permission name="apollo.replicationanalysis.readwrite">true</permission>
<permission name="apollo.datacollectionpolicy.read">true</permission>
<permission name="apollo.global.readwrite">true</permission>
<permission name="apollo.alerts.readwrite">true</permission>
<permission name="apollo.inventory.read">true</permission>
<permission name="apollo.datacollectionpolicy.assign">true</permission>
<permission name="apollo.user.read">true</permission>
<permission name="apollo.scheduledreports.readwrite">true</permission>
<permission name="apollo.user.readwrite">true</permission>
<permission name="apollo.protectionpolicy.read">true</permission>
<permission name="apollo.protectionpolicy.assign">true</permission>
</permissions>
</userRole>
<status>ENABLED</status>
</user>
<licensed>true</licensed>
<serverTimeZone>America/New_York</serverTimeZone>
</serverStatus>
7
Engineers’ Guide to Using DPA REST API 6.3
=========================F I N I S H===========================
Example
dpa app query -t https://localhost:9002 -p dpa-api/server/status -m GET -l administrator
-hd "Content-Type:application/vnd.emc.apollo-v1+xml" -a
Where:
• -t - Host where DPA is installed. In thecurrent example it is https://localhost:90024
• -p - REST API path. In the current example it is dpa-api/server/status
• -m - Method of the HTTP request. In the current example it is GET
• -l - User name of DPA for authorization. In the current example it is administrator
• -hd - List of headers. In the current example we use only one header. Where header name is
Content-Type and header value is application/vnd.emc.apollo-v1+xml
• -a - flag for DPA authorization
Example
dpa app query -api server-status -t https://10.76.244.77:9002 -l user -hd "Accept:
*/*::Accept-Encoding: gzip,deflate,sdch" -a
where:
• -api server-status - As you can see we point to "server-status" request as based request
• -t - In command-line we override https://localhost:9002 to https://10.76.244.77:9002
• -l - We override administrator to user
• -hd - We add new 2 headers Accept: */* and Accept-Encoding: gzip,deflate,sdch
• -a - flag for DPA authorization
8
Engineers’ Guide to Using DPA REST API 6.3
Entity
Content-Type : application/vnd.emc.apollo-v1+xml
Transport
Host: 10.76.224.77:9002
Attribute Description
9
Engineers’ Guide to Using DPA REST API 6.3
https://localhost:9002/dpa-api/meta
This resource call will return a XML document outlining the available RESTful API calls on the varuous internal
resources managed by DPA.
<resource>
<path>/license</path>
<methods>
<method verb="GET">
<path>/license/{id :[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}}</path>
<since>6.2</since>
<revision>1</revison>
<description></description>
<produces>
<type>application/vnd.emc.apollo-v1+xml</type>
</produces>
</method>
<method verb="GET">
<path>/license</path>
<since>6.2</since>
<revision>1</revison>
<description></description>
<produces>
<type>application/vnd.emc.apollo-v2+xml</type>
</produces>
</method>
10
Engineers’ Guide to Using DPA REST API 6.3
The Apollo API provides access to the low level services on which DPA is built and in most cases in not expected to
be widely used. The DPA API provides the richer, higher value API to DPA functionality and is expected to more
widely utilized for integration of DPA with other applications.
In the following sections some ‘real world’ examples are presented, utilizing a number of different RESTful API
client technologies, to demonstrate the practical use of the DPA REST API.
Additional REST information, which may be of assistance to diagnose development issues, will be placed in the
following location:
<install_directory>/services/logs/server.log
11
Engineers’ Guide to Using DPA REST API 6.3
PREREQUISITES:
• Download the client from https://github.com/wiztools/rest-client/releases
• Select https://github.com/wiztools/rest-client/releases/download/3.6.1/restclient-cli-fat-3.6.1.jar
PROCEDURE:
URL : https://<dpaserver>:9002/apollo-api/nodes/?query=name%3d<hostname>
Eg: https://localhost:9002/apollo-api/nodes/?query=name%3ddpavqavamar71.datadomain.com
12
Engineers’ Guide to Using DPA REST API 6.3
Key : Content-Type
Value : application/vnd.emc.apollo-v1+xml
When communicating properly the HTTP response status shows HTTP/1.1 200 OK.
Content-Type: application/vnd.emc.apollo-v1+xml
g. Select the HTTP Response Body tab and look for the ID in the contents of the body. This will look
somethinglike: <id> 53ddf53d-ed58-461c-a1f9-a0a9e285e0d6</id>
Copy the ID string into your clip board. You will use it later to acquire the report.
13
Engineers’ Guide to Using DPA REST API 6.3
<runReportParameters>
<report>
<name>Backup All Jobs</name> <!-- Report template name -->
</report>
<nodes>
<node>
<id> 53ddf53d-ed58-461c-a1f9-a0a9e285e0d6 </id> <!-- scope - node id of the Host -->
</node>
</nodes>
<timeConstraints type="window">
<window >
<name>Last Month</name> <!-- time period name -->
</window>
</timeConstraints>
<formatParameters>
<formatType>CSV</formatType> <!-- format type, could be CSV, HTML, PDF, IMAGE, XML. -->
</formatParameters>
</runReportParameters>
Replace the <id> with the Node ID obtained from the previous step.
14
Engineers’ Guide to Using DPA REST API 6.3
a. On HTTP Response, in Header tab, copy the selected Header shown below:
15
Engineers’ Guide to Using DPA REST API 6.3
eg: https://<dpaserver>/dpa-api/report/result/b7d34e30-a9b7-49da-be7b-0d0d876cea45
a. Paste the location into your browser and browse to it after removing excess fields.
https://<dpaserver>:9002/dpa-api/report/result/b7d34e30-a9b7-49da-be7b-0d0d876cea45
16
Engineers’ Guide to Using DPA REST API 6.3
c. Change the Format Type to HTML in the body of the HTTP Request and rerun the request
d. Copy the new location in your browser.
https://<dpaserver>:9002/dpa-api/report/result/d0009959-e78a-4f0e-82a1-741a8b1a56ac
Result:
17