Skip to main content
Hitachi Vantara Knowledge

Resources

The main types of HCP management API resources are tenants, namespaces, retention classes, content classes, tenant-level user accounts, and tenant-level group accounts. Each main type of resource is associated with a set of resource identifiers, each of which identifies one of these:

  • A list of resources of that type
  • An instance of that type of resource
  • A property of that type of resource that is treated as a resource in its own right.

A resource identifier is the portion of a resource URL that follows mapi.

Examples of using the management API to manipulate resources are also included. All examples assume an HCP system that supports Active Directory.

Additionally, this section contains instructions for paging through, sorting, and filtering the results of GET requests for namespaces, user accounts, and data access permissions.

Content class resources

Content class resources let you create, retrieve information about, modify, and delete content classes. These resources are not available for tenants that do not have search configuration enabled.

The tables below provide information about content class resources.

.../tenants/tenant-name/contentClasses
Data typeMethodUseAccessNotes
contentClassPUTCreate a content class for a tenant
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
ListGETRetrieve a list of the content classes for a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role

The listed content classes are identified by content class name.

In XML, the element that identifies each content class is name. The root element for the list of content classes is contentClasses.

In JSON, the name in the name/value pair that lists the content classes is name.

.../tenants/tenant-name/contentClasses/content-class-name
Data typeMethodUseAccessNotes
contentClassGETRetrieve information about a content class
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
N/AHEADCheck for the existence of a content class
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
contentClassPOSTModify a content class
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
N/ADELETEDelete a content class
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
The content class cannot contain any content properties.

Example: Creating a content class

Here’s a sample PUT request that creates a content class named DICOM and associates it with the Medical-Records namespace, which is search enabled. The content class is defined in an XML file named dicom.xml. The request is made using a tenant-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<contentClass>
    <name>DICOM</name>
    <contentProperties>
        <contentProperty>
            <name>Doctor_Name</name>
            <expression>/dicom_image/doctor/name</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Doctor_Specialty</name>
            <expression>/dicom_image/doctor/specialties/specialty</expression>
            <type>STRING</type>
            <multivalued>true</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Followup_Needed</name>
            <expression>/dicom_image/followup_needed</expression>
            <type>BOOLEAN</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Image_Date</name>
            <expression>/dicom_image/image/date</expression>
            <type>DATE</type>
            <multivalued>false</multivalued>
            <format>MM/dd/yyyy</format>
        </contentProperty>
        <contentProperty>
            <name>Image_Type</name>
            <expression>/dicom_image/image/@type</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Patient_ID</name>
            <expression>/dicom_image/patient/id</expression>
            <type>INTEGER</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
        <contentProperty>
            <name>Patient_Name</name>
            <expression>/dicom_image/patient/name</expression>
            <type>STRING</type>
            <multivalued>false</multivalued>
            <format></format>
        </contentProperty>
    </contentProperties>
    <namespaces>
        <name>Medical-Records</name>
    </namespaces>
</contentClass>
Request with cURL command line
curl -k -iT dicom.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://anytown-general-hospital.hcp.example.com:9090/mapi/tenants/
    anytown-general-hospital/contentClasses"
Request in Python using PycURL
import pycurl
import os
filehandle = open("dicom.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://anytown-general-hospital.hcp.example.com:9090/mapi/" +
  "tenants/anytown-general-hospital/contentClasses")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("dicom.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants/anytown-general-hospital/contentClasses HTTP/1.1
Host: anytown-general-hospital.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 2702
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving a list of content classes

Here’s a sample GET request that retrieves a list of the content classes defined for the Anytown-General-Hospital tenant. The request writes the list of content classes to a file named AGH-cc.xml. The request is made using a tenant-level user account that includes the administrator role.

Request with cURL command line
curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://anytown-general-hospital.hcp.example.com:9090/mapi/tenants/
        anytown-general-hospital/contentClasses?prettyprint" > AGH-cc.xml
Request in Python using PycURL
import pycurl
filehandle = open("AGH-cc.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://anytown-general-hospital.hcp.example.com:9090/mapi/" +
  "tenants/anytown-general-hospital/contentClasses")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/tenants/anytown-general-hospital/contentClasses?prettyprint HTTP/1.1
Host: anytown-general-hospital.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 143
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contentClasses>
    <name>Appointment</name>
    <name>DICOM</name>
</contentClasses>

Erasure coding topology resources

Erasure coding topology resources let you create, specify tenants for, modify, retire, and delete erasure coding topologies. The table below provides information about these resources.

.../services/erasureCoding/ecTopologies
Data typeMethodUseAccessNotes
ecTopologyPUTCreate an erasure coding topologySystem-level user account with the administrator role
ListGETRetrieve a list of the existing erasure coding topologiesSystem-level user account with the monitor or administrator role

The listed erasure coding topologies are identified by erasure coding topology name.

In XML, the element that identifies each erasure coding topology is name. The root element for the list of erasure coding topologies is ecTopologies.

In JSON, the name in the name/value pair that lists the erasure coding topologies is name.

.../services/erasureCoding/ecTopologies/ec-topology-name
Data typeMethodUseAccessNotes
ecTopologyGETRetrieve information about an erasure coding topologySystem-level user account with the monitor or administrator role
N/AHEADCheck for the existence of an erasure coding topologySystem-level user account with the monitor or administrator role
ecTopologyPOSTModify or retire an erasure coding topologySystem-level user account with the administrator role
N/ADELETEDelete an erasure coding topologySystem-level user account with the administrator role
.../services/erasureCoding/ecTopologies/ec-topology-name/tenantCandidates
Data typeMethodUseAccessNotes
tenant CandidatesGETRetrieve a list of the tenants that are eligible to be added to an erasure coding topologySystem-level user account with the monitor or administrator role
.../services/erasureCoding/ecTopologies/ec-topology-name/tenantConflictingCandidates
Data typeMethodUseAccessNotes
tenant CandidatesGETRetrieve a list of tenants that are not eligible to be added to an erasure coding topoloty due to name or link conflictsSystem-level user account with the monitor or administrator role
.../services/erasureCoding/ecTopologies/ec-topology-name/tenants
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the tenants that are included in a replication topologySystem-level user account with the monitor or administrator role

In XML, the element that identifies each tenant is name. The root element for the list of tenants is tenants.

In JSON, the name in the name/value pair that lists the tenants is name.

.../services/erasureCoding/ecTopologies/ec-topology-name/tenants/tenant-name
Data typeMethodUseAccessNotes
StringPUTAdd a tenant to an erasure coding topologySystem-level user account with the administrator roleWith cURL, you need to use -X PUT, not -T, in a request to add a tenant to an erasure coding topology.
StringDELETERemove a tenant from an erasure coding topologySystem-level user account with the administrator role
.../services/erasureCoding/linkCandidates
Data typeMethodUseAccessNotes
repliationLinksGETRetrieve a list of the replication links that may be eligible for use in an erasure coding topology that includes the local HCP systemSystem-level user account with the monitor or administrator role

Example: Retrieving a list of eligible replication links

Here's a sample GET request that retrieves a list of all the active/active replication links that directly connect the local HCP system to another HCP system or that are in a path of active/active links that indirectly connect the local system to another system. The request writes the list of links to a file named eligible-links.xml. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        linkCandidates?verbose=true&prettyprint" > eligible-links.xml
Request in Python using PycURL
import pycurl
filehandle = open("eligible-links.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/linkCandidates?verbose=true&prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/services/erasureCoding/linkCandidates?verbose=true&prettyprint HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 2154
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<replicationLinks>
    <replicationLink>
        <hcpSystems>
            <name>hcp-ca.example.com</name>
            <name>hcp-eu.example.com</name>
        </hcpSystems>
        <name>eu-ca</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>7ae4101c-6e29-426e-ae71-9a7a529f019d</uuid>
    </replicationLink>
    <replicationLink>
        <hcpSystems>
            <name>hcp-ca.example.com</name>
            <name>hcp-us.example.com</name>
        </hcpSystems>
        <name>us-ca</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>cdb7edcd-feb6-4476-8d8d-bd053e3bc2ee</uuid>
    </replicationLink>
    <replicationLink>
        <hcpSystems>
            <name>hcp-an.example.com</name>
            <name>hcp-eu.example.com</name>
        </hcpSystems>
        <name>eu-an</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>77037ade-0115-4e30-a043-725f1bbcd87f</uuid>
    </replicationLink>
    <replicationLink>
        <hcpSystems>
            <name>hcp-eu.example.com</name>
            <name>hcp-us.example.com</name>
        </hcpSystems>
        <name>us-eu</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>32871da5-2355-458a-90f5-1717aa684d6f</uuid>
    </replicationLink>
    <replicationLink>
        <hcpSystems>
            <name>hcp-an.example.com</name>
            <name>hcp-us.example.com</name>
        </hcpSystems>
        <name>us-an</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>c8c875ad-dbfe-437d-abd3-862a6c719894</uuid>
    </replicationLink>
    <replicationLink>
        <hcpSystems>
            <name>hcp-an.example.com</name>
            <name>hcp-ca.example.com</name>
        </hcpSystems>
        <name>ca-an</name>
        <pausedTenantsCount>0</pausedTenantsCount>
        <state>HEALTHY</state>
        <uuid>a1f21e03-fb46-48cc-967e-b0cedf80bb20</uuid>
    </replicationLink>
</replicationLinks>

Example: Creating an erasure coding topoology

Here's a sample PUT request that creates a four-system erasure coding topology named ex-corp-4. The topology definition is in an XML file named create-ect.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ecTopology>
    <name>ex-corp-4</name>
    <description>Erasure coding topology for the US, Europe, Canada, and Africa-North
        divisions.</description>
    <type>ring</type>
    <replicationLinks>
        <replicationLink>
            <name>us-eu</name>
        </replicationLink>
        <replicationLink>
            <name>eu-ca</name>
        </replicationLink>
        <replicationLink>
            <name>ca-an</name>
        </replicationLink>
        <replicationLink>
            <name>us-an</name>
        </replicationLink>
    </replicationLinks>
    <erasureCodingDelay>10</erasureCodingDelay>
    <fullCopy>false</fullCopy>
    <minimumObjectSize>4096</minimumObjectSize>
    <restorePeriod>5</restorePeriod>
</ecTopology>
Request with cURL command line
curl -k -T create-ect.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        ecTopologies"
Request in Python using PycURL
import pycurl
import os
filehandle = open("create-ect.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/ecTopologies")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("create-ect.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/services/erasureCoding/ecTopologies HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Content-Type: application/xml
Content-Length: 775
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving a list of eligible tenants

Here's a sample GET request that retrieves a list of all the local and remote tenants that are eligible to be included in the erasure coding topology named ex-corp-4. The request writes the list of tenants to a file named eligible-tenants.xml. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        ecTopologies/ex-corp-4/tenantCandidates?verbose=true&prettyprint"
    > eligible-tenants.xml
Request in Python using PycURL
import pycurl
filehandle = open("eligible-tenants.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/ecTopologies/ex-corp-4/tenantCandidates" +
  "?verbose=true&prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/services/erasureCoding/ecTopologies/ex-corp-4/tenantCandidates
    ?verbose=true&prettyprint HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 976
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tenantCandidates>
    <tenantCandidate>
        <hcpSystems>
            <name>hcp-us.example.com</name>
        </hcpSystems>
        <name>exec</name>
        <uuid>26112ed2-bb90-4e34-b450-4bf365a927d9</uuid>
    </tenantCandidate>
    <tenantCandidate>
        <hcpSystems>
            <name>hcp-us.example.com</name>
        </hcpSystems>
            <name>finance</name>
        <uuid>838cd575-0f94-489a-8f94-f36c1337c446</uuid>
    </tenantCandidate>
    <tenantCandidate>
        <hcpSystems>
            <name>hcp-eu.example.com</name>
        </hcpSystems>
        <name>research-dev</name>
        <uuid>38e7bc78-c700-4627-af63-a3c19eb77406</uuid>
    </tenantCandidate>
    <tenantCandidate>
        <hcpSystems>
            <name>hcp-us.example.com</name>
        </hcpSystems>
        <name>sales-mktg</name>
        <uuid>f349387f-18d0-49e2-9bcd-a8ac6f7952c5</uuid>
    </tenantCandidate>
</tenantCandidates>

Example: Adding a tenant to an erasure coding topology

Here's a sample GET request that adds a tenant named finance to an erasure coding topology named ex-corp-4. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -X PUT
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        ecTopologies/ex-corp-4/tenants/finance"
Request in Python using PycURL
import pycurl
import os
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/ecTopologies/ex-corp-4/tenants/finance")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
PUT /mapi/services/erasureCoding/ecTopologies/ex-corp-4/tenants/finance HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Accept:*/*
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving an erasure coding topology

Here's a sample GET request that retrieves an erasure coding topology named ex-corp-4. The request writes the output to a file named ex-corp-4.xml. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        ecTopologies/ex-corp-4?verbose=true&prettyprint" > ex-corp-4.xml
Request in Python using PycURL
import pycurl
filehandle = open("ex-corp-4.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/ecTopologies/ex-corp-4?verbose=true&prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/services/erasureCoding/ecTopologies/ex-corp-4?verbose=true&prettyprint
    HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 2402
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ecTopology>
    <description>Erasure coding topology for the US, Europe, Canada, and
        Africa-North divisions.</description>
    <erasureCodedObjects>3289</erasureCodedObjects>
    <erasureCodingDelay>10</erasureCodingDelay>
    <fullCopy>false</fullCopy>
    <hcpSystems>
        <name>hcp-an.example.com</name>
        <name>hcp-ca.example.com</name>
        <name>hcp-eu.example.com</name>
        <name>hcp-us.example.com</name>
    </hcpSystems>
    <id>faa9b2e5-a8b0-4211-ac83-6a25dff50800</id>
    <minimumObjectSize>4096</minimumObjectSize>
    <name>ex-corp-4</name>
    <protectionStatus>HEALTHY</protectionStatus>
    <readStatus>HEALTHY</readStatus>
    <replicationLinks>
        <replicationLink>
            <hcpSystems>
                <name>hcp-ca.example.com</name>
                <name>hcp-eu.example.com</name>
            </hcpSystems>
            <name>eu-ca</name>
            <pausedTenantsCount>0</pausedTenantsCount>
            <state>HEALTHY</state>
            <uuid>7ae4101c-6e29-426e-ae71-9a7a529f019d</uuid>
        </replicationLink>
        <replicationLink>
            <hcpSystems>
                <name>hcp-eu.example.com</name>
                <name>hcp-us.example.com</name>
            </hcpSystems>
            <name>us-eu</name>
            <pausedTenantsCount>0</pausedTenantsCount>
            <state>HEALTHY</state>
            <uuid>32871da5-2355-458a-90f5-1717aa684d6f</uuid>
        </replicationLink>
        <replicationLink>
            <hcpSystems>
                <name>hcp-an.example.com</name>
                <name>hcp-us.example.com</name>
            </hcpSystems>
            <name>us-an</name>
            <pausedTenantsCount>0</pausedTenantsCount>
            <state>HEALTHY</state>
            <uuid>c8c875ad-dbfe-437d-abd3-862a6c719894</uuid>
        </replicationLink>
        <replicationLink>
            <hcpSystems>
                <name>hcp-an.example.com</name>
                <name>hcp-ca.example.com</name>
            </hcpSystems>
            <name>ca-an</name>
            <pausedTenantsCount>0</pausedTenantsCount>
            <state>HEALTHY</state>
            <uuid>a1f21e03-fb46-48cc-967e-b0cedf80bb20</uuid>
        </replicationLink>
    </replicationLinks>
    <restorePeriod>5</restorePeriod>
    <state>ACTIVE</state>
    <tenants>
        <name>research-dev</name>
        <name>sales-mktg</name>
        <name>exec</name>
        <name>finance</name>
    </tenants>
    <type>RING</type>
</ecTopology>

Example: Retiring an erasure coding topology

Here's a sample POST request that retires an erasure coding topology named ex-corp-4. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -d "<ecTopology/>"
    -H "Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp-us.example.com:9090/mapi/services/erasureCoding/
        ecTopologies/ex-corp-4?retire"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-us.example.com:9090/mapi/services/" +
  "erasureCoding/ecTopologies/ex-corp-4?retire")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
POST /mapi/services/erasureCoding/ecTopologies/ex-corp-4?retire HTTP/1.1
Host: admin.hcp-us.example.com:9090
Authorization: HCP bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97
Accept: */*
Content-Length: 13
Content-Type: application/x-www-form-urlencoded
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Health check report resources

Health check report resources let you prepare, download, cancel, and retrieve the status of HCP health check reports.

.../healthCheckReport
Data typeMethodUseAccessNotes
healthCheckDownloadStatusGETRetrieve the status of the health check reports download in progress.System-level user with the administrator or service role
.../healthCheckReport/prepare
Data typeMethodUseAccessNotes
healthCheckPreparePOSTPost a system request to prepare the health check reports.System-level user with the administrator or service roleHealth check reports can be prepared only on nodes that are running and available.
.../healthCheckReport/download
Data typeMethodUseAccessNotes
healthCheckDownloadPOSTPost a system request to start the health check reports download.System-level user with the administrator or service roleThe health check reports archive can be downloaded at any time after the health check reports are successfully prepared.
.../healthCheckReport/cancel

This resource has no data types.

Example: Preparing health check reports for download

Here is a sample POST request that prepares health check reports for download. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -iX POST -d @HealthCheckPrepare.xml -k -H "Content-type: application/xml"
 -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
 "https://admin.hcp.example.com:9090/mapi/healthCheckReport/prepare"
Request headers
POST /mapi/healthCheckReport/prepare HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5
Content-Type: application/xml
Content-Length: 37
Example: Request body
<healthcheckPrepare>
     <startDate>09/19/2020</startDate>
     <endDate>09/21/2020</endDate>
     <exactTime>04:00</exactTime>
     <collectCurrent>false</collectCurrent>
</healthcheckPrepare>
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.2.27
Content-Length: 0

Example: Downloading the health check reports

Here is a sample POST request that downloads a health check reports archive. The request downloads the reports for HCP nodes 107 and 120, as specified in an XML file named HealthCheckDownload.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<healthCheckDownload>
     <nodes>107,120</nodes>
     <content>HCR</content>
</healthCheckDownload>
Request with cURL command line
curl -X POST -T HealthCheckDownload.xml -H "Content-Type: application/xml"
 -k -b hcp-api-auth="HCP ZGVa3b9c17d52107f34fhdb83c7a5"
 https://admin.hcp.example.com:9090/mapi/healthCheckReport/download
Request headers
POST /mapi/healthCheckReport/download HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.1.0
Content-Length: 575

Example: Retrieving the health check reports download status

Here is a sample GET request that retrieves the health check reports download status. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -b hcp-api-auth="HCP ZGVa3b9c17d52107f34fhdb83c7a5"
 https://admin.hcp.example.com:9090/mapi/healthCheckReport?prettyprint
Request headers
GET /mapi/healthCheckReport HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.2.27
Content-Length: 383
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<healthCheckDownloadStatus>
     <readyForStreaming>true</readyForStreaming>
     <streamingInProgress>false</streamingInProgress>
     <error>false</error>
     <started>true</started>
     <content>HCR</content>
</healthCheckDownloadStatus>

Example: Canceling the health check reports

Here is a sample POST request that cancels the health check reports download. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -X POST -k -b hcp-api-auth="HCP ZGVa3b9c17d52107f34fhdb83c7a5"
 -H "Accept: application/xml" https://admin.hcp.example.com:9090/mapi/healthCheckReport?cancel
Request headers
POST /mapi/healthCheckReport?cancel HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.1.0
Content-Length: 0

License resources

License resources let you upload a license key and retrieve the current license or a list of the current and past licenses.

.../storage/licenses
Data typeMethodUseAccessNotes
LicensesGETRetrieve either the current storage license or a list of the current and past storage licensesSystem-level user account with the monitor or administrator role

HCP does not return information about licensing of S Series storage.

To display the list of current and past storage licenses, use the verbose query parameter.

N/APUTUpload a new storage licenseSystem-level user account with the administrator roleWith the PUT request, you need to supply a the license text key string.

Example: Retrieving a premium storage license list

Here is a sample GET request that retrieves the current premium storage license information. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/storage/licenses?prettyprint"
Request in Python using PycURL
import pycurl
filehandle = open("HCPLic_SN12345_Q0123456789_A10TB_01-01-2021.plk",
  'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/storage/licenses?" +
  "prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/storage/licenses?prettyprint HTTP/1.1
Host: admin.hcp.example.com:9090
Accept: application/xml
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 356
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<licenses>
     <license>
         <activeCapacity>10000000000000</activeCapacity>
         <expirationDate>Jan 1, 2025</expirationDate>
         <extendedCapacity>0</extendedCapacity>
         <licenseType>Premium</licenseType>
         <serialNumber>12345</serialNumber>
         <uploadDate>Aug 14, 2020</uploadDate>
     </license>
</licenses>

Example: Uploading a new license

Here’s a sample PUT request that uploads a storage license. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -i -k -H "Content-Type: text/html"
    -H "Authorization=HCP YWxscm9sZXM=:04ec9f614d89ff5c7126d32acb448382"
    -X PUT -d
    "450a4346cac1d4d49c719312caed27f4f582ba1024b342a0f10be7a7283e6f8acba69e5c"
    "https://admin.hcp.example.com:9090/mapi/storage/licenses"
Request in Python using PycURL
import pycurl
import os
readString = "450a4346cac1d4d49c719312caed27f4f582ba1024b342a0f10be7a7283e6f8acba69e5c",
curl = pycurl.Curl()
curl.setopt(curl.HTTPHEADER, ["Content-Type: text/html", "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/storage/licenses”)
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.setopt(pycurl.POSTFIELDS, readString)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/services/replication/links HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: text/html
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Log resources

Log resources let you prepare, download, and monitor the download of the HCP internal logs.

.../logs
Data typeMethodUseAccessNotes
LogDownloadStatusGETRetrieve the status of the log download in progressSystem-level user with the administrator, service, or monitor role.
N/APOSTMarks the logs with a supplied messageSystem-level user with the administrator or service role.You supply the message at the end of the command. Use the plus (+) sign or %20 to make spaces between words.
N/APOSTClears the log download so that it can be reinitiated.System-level user with the administrator or service role.
.../logs/prepare
Data typeMethodUseAccessNotes
LogPreparePOSTPost a system request to package logs for downloadSystem-level user with the administrator or service role.Packages all logs, regardless of log type. If prepared logs are not downloaded withing twenty four hours, the package is deleted.
.../logs/download
Data typeMethodUseAccessNotes
LogDownloadPOSTStarts the log downloadSystem-level user with the administrator or service role.Downloaded logs come as .zip files. For HCP nodes, you have control over which log types are downloaded.

Example: Start log packaging

Here’s a sample POST request that packages system logs for download. The command requests to package logs between the dates of 8/19/2017 and 8/21/2017. The dates are specified in an XML file named logPrepare.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<logPrepare>
    <startDate>08/19/2017</startDate>
    <endDate>08/21/2017</endDate>
</logPrepare>
Request with cURL command line
curl -iX POST -d @logPrepare.xml -k -i -H "Content-type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/logs/prepare"
Request in Python using PycURL
import pycurl
import os
filename = "logPrepare.xml"
filehandle = open(filename, "rb")
filesize = os.path.getsize(filename)
curl = pycurl.Curl()
curl.setopt(pycurl.VERBOSE, True)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml", \
"Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL, "https://admin.hcp.example.com:9090/mapi/logs/prepare")
curl.setopt(pycurl.SSL_VERIFYPEER, False)
curl.setopt(pycurl.SSL_VERIFYHOST, False)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, filesize)
curl.perform()
filehandle.close()
curl.close()
Request headers
POST /mapi/logs/prepare HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 56
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Download the logs

Here’s a sample POST request that downloads the system logs prepared in the previous example to your current directory in a zip file. The request downloads the Service logs for General Node 17. The log type and selected General Node are specified in an XML file named logDownload.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<logDownload>
    <nodes>17</nodes>
    <content>SERVICE</content>
</logDownload>
Request with cURL command line
curl -X POST -T @logDownload.xml -k -H "Content-type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/logs/download"
    -o logDownload.zip
Request in Python using PycURL
import pycurl
import os
filename = "logDownload.xml"
filehandle = open(filename, "rb")
filesize = os.path.getsize(filename)
output = open("downloadedLogs.zip", "wb")
curl = pycurl.Curl()
curl.setopt(pycurl.VERBOSE, True)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml", \
"Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL, "https://admin.hcp.example.com:9090/mapi/logs/download")
curl.setopt(pycurl.SSL_VERIFYPEER, False)
curl.setopt(pycurl.SSL_VERIFYHOST, False)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, filesize)
curl.setopt(pycurl.WRITEFUNCTION, output.write)
curl.perform()
print(curl.getinfo(pycurl.RESPONSE_CODE))
filehandle.close()
curl.close()
Request headers
POST /mapi/logs/download HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename=HCPLogs-admin.hcp.example.com-n17-sp20170321-1225.zip
Accept-Ranges: none
Transfer-Encoding: chunked

Example: Retrieving the log download status

Here’s a sample GET request that retrieves the log download status. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -i
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/logs"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.VERBOSE, True)
curl.setopt(pycurl.CUSTOMREQUEST, "GET")
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml", \
"Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL, "https://admin.hcp.example.com:9090/mapi/logs?prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, False)
curl.setopt(pycurl.SSL_VERIFYHOST, False)
curl.perform()
curl.close()
Request headers
GET /mapi/logs HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 282
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<logDownloadStatus>
    <readyForStreaming>true</readyForStreaming>
    <streamingInProgress>false</streamingInProgress>
    <started>true</started>
    <error>false</error>
    <content>SERVICE</content>
</logDownloadStatus>

Example: Canceling a log download

Here’s a sample POST request that clears the log download status. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -X POST -k -i
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/logs?cancel"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.VERBOSE, True)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL, "https://admin.hcp.example.com:9090/mapi/logs?cancel")
curl.setopt(pycurl.SSL_VERIFYPEER, False)
curl.setopt(pycurl.SSL_VERIFYHOST, False)
curl.perform()
curl.close()
Request headers
POST /mapi/logs?cancel HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Marking the download log

Here’s a sample POST request that marks the system logs with the message Mark the log. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -X POST -k -i
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/logs?mark=Mark+the+log"
Request in Python using PycURL
import pycurl
markMessage = "Mark+the+log"
curl = pycurl.Curl()
curl.setopt(pycurl.VERBOSE, True)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL, ("https://admin.hcp.example.com:9090/mapi/logs/?" +
  "mark="Mark+the+log"))
curl.setopt(pycurl.SSL_VERIFYPEER, False)
curl.setopt(pycurl.SSL_VERIFYHOST, False)
curl.perform()
curl.close()
Request headers
POST /mapi/logs?mark=Mark+the+log HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Namespace resources

Namespace resources let you create, retrieve information about, modify, and delete namespaces. The table below provides information about these resources.

.../tenants/tenant-name/namespaces
Data typeMethodUseAccessNotes
namespacePUTCreate an HCP namespaceTenant-level user account with the administrator role or allow namespace management propertyNot valid for the default namespace.
ListGETRetrieve a list of the namespaces owned by a tenant
  • For an HCP tenant, tenant-level user account with the monitor, administrator, or compliance role or allow namespace management property
  • For the default tenant, system-level user account with the monitor or administrator role

The listed namespaces are identified by namespace name.

In XML, the element that identifies each namespace is name. The root element for the list of namespaces is namespaces.

In JSON, the name in the name/value pair that lists the namespaces is name.

For a user with the allow namespace management property and no roles, the retrieved list includes only the namespaces the user owns.

.../tenants/tenant-name/namespaces/cors
Data typeMethodUseAccessNotes
corsPUTSet the CORS rules configuration for a namespace
  • System-level user account with the administrator role
  • Tenant-level user account with the administrator role
A CORS configuration set on a namespace overrides the default tenant-level CORS configuration.
GETRetrieve the CORS configuration for a namespace
  • System-level user account with the monitor or administrator role
  • Tenant-level user account with the monitor or administrator role
DELETEDelete the CORS configuration for a namespace
  • System-level user account with the administrator role
  • Tenant-level user account with the administrator role
If a CORS configuration is not set on the namespace, the HTTP status code 404 Not Found is returned.
.../tenants/tenant-name/namespaces/namespace-name
Data typeMethodUseAccessNotes
namespaceGETRetrieve information about a namespace
  • For an HCP namespace, tenant-level user account with the monitor or administrator role or allow namespace management property
  • For the default namespace, system-level user account with the monitor or administrator role
A user with the allow namespace management property and no roles can retrieve information only about the namespaces the user owns. In this case, the retrieved information includes only the namespace name and owner.
N/AHEADCheck for the existence of a namespace
  • For an HCP namespace, tenant-level user account with the monitor, administrator, or compliance role or allow namespace management property
  • For the default namespace, system-level user account with the monitor or administrator role
namespacePOSTModify a namespace
  • For an HCP namespace, tenant-level user account with the administrator role
  • For the default namespace, system-level user account with the administrator role
N/ADELETEDelete an HCP namespaceTenant-level user account with the administrator role or allow namespace management property

A user with the allow namespace management property and no roles can delete only the namespaces the user owns.

The namespace cannot contain any objects.

Not valid for the default namespace.

.../tenants/tenant-name/namespaces/namespace-name/chargebackReport
Data typeMethodUseAccessNotes

chargeback

Report

GETGenerate a chargeback report for a namespaceTenant-level user account with the monitor or administrator role

Not valid for the default namespace.

Supported output formats are XML, JSON, and CSV.

.../tenants/tenant-name/namespaces/namespace-name/complianceSettings
Data typeMethodUseAccessNotes
compliance SettingsGETRetrieve the default retention, shred, custom metadata handling, and disposition settings for a namespace
  • For an HCP namespace, tenant-level user account with the monitor, administrator, or compliance role
  • For the default namespace, system-level user account with the monitor, administrator, or compliance role
Default retention and shred settings do not apply to the default namespace.
POSTModify the default retention, shred, custom metadata handling, or disposition setting for a namespace
  • For an HCP namespace, tenant-level user account with the compliance role
  • For the default namespace, system-level user account with the compliance role
../tenants/tenant-name/namespaces/namespace-name/customMetadataIndexingSettings
Data typeMethodUseAccessNotes
custom Metadata Indexing SettingsGETRetrieve settings specific to metadata query engine indexing of custom metadata for a search-enabled namespace
  • For an HCP namespace, tenant-level user account with the monitor or administrator role
  • For the default namespace, system-level user account with the monitor or administrator role
Not valid for namespaces that do not have search enabled.
POSTModify settings specific to metadata query engine indexing of custom metadata for a search-enabled namespace
  • For an HCP namespace, tenant-level user account with the administrator role
  • For the default namespace, system-level user account with the administrator role
.../tenants/tenant-name/namespaces/namespace-name/permissions
Data typeMethodUseAccessNotes
ListGETRetrieve the list of permissions in the data access permission mask for a namespace
  • For an HCP namespace, tenant-level user account with the monitor or administrator role
  • For the default namespace, system-level user account with the monitor or administrator role
ListPOSTModify the list of permissions in the data access permission mask for a namespace
  • For an HCP namespace, tenant-level user account with the administrator role
  • For the default namespace, system-level user account with the administrator role

Valid values for permissions are:

  • DELETE
  • PRIVILEGED
  • PURGE
  • READ
  • SEARCH
  • WRITE

These values are case sensitive.

The set of permissions specified in the request body replaces the set of permissions currently included in the data access permission mask for the namespace. To remove all permissions, specify an empty list.

If the set of permissions includes PURGE, delete permission is enabled automatically. If the set of permissions includes SEARCH, read permission is enabled automatically.

By default, when you create a namespace, its data access permission mask includes all permissions.

.../tenants/tenant-name/namespaces/namespace-name/protocols
Data typeMethodUseAccessNotes
protocolsGETRetrieve a subset of the HTTP namespace access protocol settings for the default namespaceSystem-level user account with the monitor or administrator roleNot valid for HCP namespaces. For HCP namespaces, this resource has been superseded by the .../protocols/http resource.
POSTModify a subset of the HTTP namespace access protocol settings for the default namespaceSystem-level user account with the administrator role
.../tenants/tenant-name/namespaces/namespace-name/protocols/protocol-name
Data typeMethodUseAccessNotes
Determined by protocol-name. Possible data types are:
  • cifsProtocol
  • httpProtocol
  • nfsProtocol
  • smtpProtocol
GETRetrieve the applicable namespace access protocol settings for a namespaceTenant-level user account with the monitor or administrator role

Not valid for the default namespace.

Valid values for protocol-name are:

  • cifs
  • http
  • nfs
  • smtp

These values are case sensitive.

The httpProtocol data type includes properties for both the HTTP and WebDAV protocols.

POSTModify the applicable namespace access protocol settings for a namespaceTenant-level user account with the administrator role
.../tenants/tenant-name/namespaces/namespace-name/replicationCollisionSettings
Data typeMethodUseAccessNotes
replication Collision SettingsGETRetrieve the replication collision handling settings for a namespace
  • For an HCP namespace, tenant-level user account with the monitor or administrator role
  • For the default namespace, system-level user account with the monitor or administrator role
POSTModify the replication collision handling settings for a namespace
  • For an HCP namespace, tenant-level user account with the administrator role
  • For the default namespace, system-level user account with the administrator role
.../tenants/tenant-name/namespaces/namespace-name/statistics
Data typeMethodUseAccessNotes
statisticsGETRetrieve information about the content of a namespace
  • For an HCP namespace, tenant-level user account with the monitor or administrator role
  • For the default namespace, system-level user account with the monitor or administrator role
.../tenants/tenant-name/namespaces/namespace-name/versioningSettings
Data typeMethodUseAccessNotes

versioning

Settings

GETRetrieve the versioning settings for a namespaceTenant-level user account with the monitor or administrator role or the allow namespace management property

A user with the allow namespace management property and no roles can retrieve and modify only the versioning enabled property and that property only for the namespaces the user owns.

Not valid for the default namespace.

POSTModify the versioning settings for a namespaceTenant-level user account with the administrator role or the allow namespace management property
DELETEDelete the versioning settings for a namespaceTenant-level user account with the monitor or administrator role or the allow namespace management property

Example: Creating an HCP namespace

Here’s a sample PUT request that creates an HCP namespace named Accounts-Receivable for the Finance tenant. The namespace definition is in an XML file named AccountsRecNS.xml. The request is made using a tenant-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<namespace>
    <name>Accounts-Receivable</name>
    <description>Created for the Finance department at Example Company by Lee
        Green on 2/9/2017.</description>
    <hashScheme>SHA-256</hashScheme>
    <enterpriseMode>true</enterpriseMode>
    <hardQuota>50 GB</hardQuota>
    <softQuota>75</softQuota>
    <servicePlan>Short-Term-Activity</servicePlan>
    <optimizedFor>CLOUD</optimizedFor>
    <versioningSettings>
        <enabled>true</enabled>
        <prune>true</prune>
        <pruneDays>10</pruneDays>
    </versioningSettings>
    <multipartUploadAutoAbortDays>10</multipartUploadAutoAbortDays>
    <searchEnabled>true</searchEnabled>
    <indexingEnabled>true</indexingEnabled>
    <customMetadataIndexingEnabled>true</customMetadataIndexingEnabled>
    <customMetadataValidationEnabled>true</customMetadataValidationEnabled>
    <replicationEnabled>true</replicationEnabled>
    <allowErasureCoding>true</allowErasureCoding>
    <readFromReplica>true</readFromReplica>
    <serviceRemoteSystemRequests>true</serviceRemoteSystemRequests>
    <tags>
        <tag>Billing</tag>
        <tag>lgreen</tag>
    </tags>
</namespace>
Request with cURL command line
curl -k -iT AccountsRecNS.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces"
Request in Python using PycURL
import pycurl
import os
filehandle = open("AccountsRecNS.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
"namespaces")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("AccountsRecNS.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants/finance/namespaces HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 1197
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example Changing the compliance settings for an HCP namespace

Here’s a sample POST request that changes the compliance settings for the Accounts-Receivable namespace. The new settings are in an XML file named AR-compliance.xml. The request is made using a tenant-level user account that includes the compliance role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<complianceSettings>
    <retentionDefault>A+7y</retentionDefault>
    <minimumRetentionAfterInitialUnspecified>19y+0M+7d</minimumRetentionAfterInitialUnspecified>
    <shreddingDefault>false</shreddingDefault>
    <customMetadataChanges>all</customMetadataChanges>
    <dispositionEnabled>true</dispositionEnabled>
</complianceSettings>
Request with cURL command line
curl -k -i -d @AR-compliance.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
         accounts-receivable/complianceSettings"
Request in Python using PycURL
import pycurl
import os
filehandle = open("AR-compliance.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
 "namespaces/accounts-receivable/complianceSettings")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
  os.path.getsize("AR-compliance.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/tenants/finance/namespaces/accounts-receivable/complianceSettings
  HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb
Content-Type: application/xml
Content-Length: 285
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example Configuring the HTTP protocol for an HCP namespace

Here’s a sample POST request that configures the HTTP protocol for the Accounts-Receivable namespace. The new settings are in an XML file named AR-http.xml. The request is made using a tenant-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<httpProtocol>
    <httpsEnabled>true</httpsEnabled>
    <httpEnabled>false</httpEnabled>
    <restEnabled>true</restEnabled>
    <restRequiresAuthentication>true</restRequiresAuthentication>
    <httpActiveDirectorySSOEnabled>true</httpActiveDirectorySSOEnabled>
    <ipSettings>
         <allowAddresses>
             <ipAddress>192.168.140.10</ipAddress>
             <ipAddress>192.168.140.14</ipAddress>
             <ipAddress>192.168.140.15</ipAddress>
             <ipAddress>192.168.149.0/24</ipAddress>
         </allowAddresses>
         <allowIfInBothLists>false</allowIfInBothLists>
         <denyAddresses>
             <ipAddress>192.168.149.5</ipAddress>
         </denyAddresses>
    </ipSettings>
</httpProtocol>
Request with cURL command line
curl -k -i -d @AR-http.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
         accounts-receivable/protocols/http"
Request in Python using PycURL
import pycurl
import os
filehandle = open("AR-http.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "namespaces/accounts-receivable/protocols/http")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
   os.path.getsize("AR-http.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/tenants/finance/namespaces/accounts-receivable/protocols/http
    HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 285
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Network resources

Network resources let you activate advanced DNS configuration mode and view the current DNS configuration setting. The table below provides information about these resources.

.../network
Data typeMethodUseAccessNotes
Network settingsGETRetrieves the current downstream DNS mode.System-level user account with the monitor or administrator role
POSTModifies the current downstream DNS mode setting for the given network.System-level user account with the administrator role

Valid values for this setting are:

  • ADVANCED
  • BASIC

Example: Enabling advanced downstream DNS configuration

Here’s a sample POST request that sets the downstream DNS mode to advanced. The DNS mode is specified in an XML file named network.xml. The request is made using a system-level user account that has the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<networkSettings>
    <downstreamDNSMode>ADVANCED</downstreamDNSMode>
</networkSettings>
Request with cURL command line
curl -k -i -d @network.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda"
    "https://admin.hcp.example.com:9090/mapi/network"
Request in Python using PycURL
import pycurl
import os
filehandle = open("network.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml", / "Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/network"
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("network.xml")) curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/network?downstreamDNSMode=ADVANCED HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda
Content-Type: application/xml
Content-Length: 141
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Checking the advanced DNS configuration

Here’s a sample GET request that lists whether the advanced DNS configuration mode is enabled or disabled. The request is made using a system-level user account that has the administrator role.

Request with cURL command line
curl -k -H "Content-Type: application/xml"
    -H "Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda"
    "https://admin.hcp.example.com:9090/mapi/network”
Request in Python using PycURL
import pycurl
import os
filehandle = open("network.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml", / "Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/network"
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "GET")
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("network.xml")) curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/network HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWRtaW4=:e00cf25ad42683b3df678c61f42c6bda
Content-Type: application/xml
Content-Length: 152
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<networkSettings>
    <downstreamDNSMode>BASIC</downstreamDNSMode>
</networkSettings>

Node statistics resource

The node statistics resource lets you retrieve the statistical information of nodes in your HCP system.

NoteA best practice is to limit your HTTP GET requests for retrieving statistics and metrics to once per hour. Polling the system more frequently can lead to system instability.
.../nodes/statistics
Data typeMethodUseAccessNotes
nodeStatisticsGETRetrieve the statistics of nodes in the HCP systemSystem-level user with the administrator or monitor role.

Example: Retrieving node statistics

Here is a sample request that retrieves node statistics for nodes in the system. In this example, statistics are collected on two nodes and two volumes on each node. Also, the management port network has been configured on each node.

Request with cURL command line
curl -ik -H "Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5" -H "Accept: application/xml" "https://admin.hcp.example.com:9090/mapi/nodes/statistics?prettyprint"
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<nodeStatistics>
     <requestTime>1528292517330</requestTime>
     <nodes>
          <node>
               <nodeNumber>17</nodeNumber>
               <frontendIpAddresses>
                    <ipAddress>172.20.35.17</ipAddress>
                    <ipAddress>2001:623:0:0:222:11ff:fec7:6584</ipAddress>
               </frontendIpAddresses>
               <backendIpAddress>172.35.14.17</backendIpAddress>
               <managementIpAddresses>
                    <ipAddress>172.20.45.17</ipAddress>
                    <ipAddress>2001:623:0:0:222:11ff:fec7:6585</ipAddress>
               </managementIpAddresses>
               <openHttpConnections>0</openHttpConnections>
               <openHttpsConnections>0</openHttpsConnections>
               <maxHttpConnections>255</maxHttpConnections>
               <maxHttpsConnections>254</maxHttpsConnections>
               <cpuUser>0.16</cpuUser>
               <cpuSystem>0.08</cpuSystem>
               <cpuMax>24</cpuMax>
               <ioWait>0.02</ioWait>
               <swapOut>0.0</swapOut>
               <maxFrontEndBandwidth>1024000</maxFrontEndBandwidth>
               <frontEndBytesRead>0.3</frontEndBytesRead>
               <frontEndBytesWritten>0.2</frontEndBytesWritten>
               <maxBackEndBandwidth>1024000</maxBackEndBandwidth>
               <backEndBytesRead>7.22</backEndBytesRead>
               <backEndBytesWritten>3.87</backEndBytesWritten>
               <maxManagementPortBandwidth>1024000</maxManagementPortBandwidth>
               <managementBytesRead>.75</managementBytesRead>
               <managementBytesWritten>.7</managementBytesWritten>
               <collectionTimestamp>1528292472000</collectionTimestamp>
               <volumes>
                    <volume>
                         <id>example090</id>
                         <blocksRead>0.0</blocksRead>
                         <blocksWritten>24.8</blocksWritten>
                         <diskUtilization>0.0</diskUtilization>
                         <transferSpeed>0.57</transferSpeed>
                         <totalBytes>10217599</totalBytes>
                         <freeBytes>37887380</freeBytes>
                         <totalInodes>10443212</totalInodes>
                         <freeInodes>40083820</freeInodes>
                    </volume>
                    <volume>
                         <id>example091</id>
                         <blocksRead>138.93</blocksRead>
                         <blocksWritten>34.0</blocksWritten>
                         <diskUtilization>0.48</diskUtilization>
                         <transferSpeed>7.82</transferSpeed>
                         <totalBytes>10223583</totalBytes>
                         <freeBytes>37940648</freeBytes>
                         <totalInodes>10223616</totalInodes>
                         <freeInodes>38073632</freeInodes>
                    </volume>
               </volumes>
          </node>
          <node>
               <nodeNumber>173</nodeNumber>
               <frontendIpAddresses>
                    <ipAddress>172.20.35.16</ipAddress>
                    <ipAddress>2001:623:0:0:222:11ff:fec7:6574</ipAddress>
               </frontendIpAddresses>
               <backendIpAddress>172.35.14.16</backendIpAddress>
               <managementIpAddresses>
                    <ipAddress>172.20.45.16</ipAddress>
                    <ipAddress>2001:623:0:0:222:11ff:fec7:6575</ipAddress>
               </managementIpAddresses>
               <openHttpConnections>0</openHttpConnections>
               <openHttpsConnections>0</openHttpsConnections>
               <maxHttpConnections>255</maxHttpConnections>
               <maxHttpsConnections>254</maxHttpsConnections>
               <cpuUser>0.06</cpuUser>
               <cpuSystem>0.06</cpuSystem>
               <cpuMax>24</cpuMax>
               <ioWait>0.0</ioWait>
               <swapOut>0.0</swapOut>
               <maxFrontEndBandwidth>1024000</maxFrontEndBandwidth>
               <frontEndBytesRead>0.17</frontEndBytesRead>
               <frontEndBytesWritten>0.1</frontEndBytesWritten>
               <maxBackEndBandwidth>1024000</maxBackEndBandwidth>
               <backEndBytesRead>5.2</backEndBytesRead>
               <backEndBytesWritten>2.7</backEndBytesWritten>
               <maxManagementPortBandwidth>1024000</maxManagementPortBandwidth>
               <managementBytesRead>.32</managementBytesRead>
               <managementBytesWritten>.27</managementBytesWritten>
               <collectionTimestamp>1528292486000</collectionTimestamp>
               <volumes>
                    <volume>
                         <id>example092</id>
                         <blocksRead>0.0</blocksRead>
                         <blocksWritten>6.8</blocksWritten>
                         <diskUtilization>0.0</diskUtilization>
                         <transferSpeed>0.27</transferSpeed>
                         <totalBytes>10473796</totalBytes>
                         <freeBytes>38456396</freeBytes>
                         <totalInodes>10458232</totalInodes>
                         <freeInodes>36383276</freeInodes>
                    </volume>
                    <volume>
                         <id>example093</id>
                         <blocksRead>13.93</blocksRead>
                         <blocksWritten>28.0</blocksWritten>
                         <diskUtilization>0.08</diskUtilization>
                         <transferSpeed>1.82</transferSpeed>
                         <totalBytes>10223583</totalBytes>
                         <freeBytes>37940648</freeBytes>
                         <totalInodes>10498423</totalInodes>
                         <freeInodes>38073632</freeInodes>
                    </volume>
               </volumes>
          </node>
     </nodes>
</nodeStatistics>

Paging, sorting, and filtering

By default, in response to a GET request for:

  • The namespaces resource, HCP returns a list of all the namespaces owned by the applicable tenant
  • The userAccounts resource, HCP returns a list of all the user accounts defined for the applicable tenant
  • The dataAccessPermissions resource, HCP returns a list of all the namespaces for which the applicable user account or group account has any permissions, along with the permissions granted for each of those namespaces

With very large numbers of these items, such requests can overload or reduce the efficiency of the client. Additionally, if you’re interested in only a small number of the listed items, finding the information you want can be difficult.

To manage the results of GET requests, you can use query parameters to page through, sort, and filter these resource lists.

Paging through resource lists

You can limit the number of items HCP returns in response to an individual GET request by specifying an offset into the applicable list and a count of the items to return. By issuing multiple such requests, you can retrieve the entire list, one manageable number of items at a time. This is called paging.

To specify the offset and count, you use these query parameters in the GET request:

  • offset=offset

    specifies the offset of the first item to include in the returned tenant or namespace list.

  • count=count

    specifies the number of items to return.

These considerations apply to paging through resource lists:

  • The offset and count parameters are valid only with the namespaces, userAccounts, and dataAccessPermissions resources.
  • The first item in the complete list is at offset zero. So, for example, to retrieve the first five items, you would specify offset=0 and count=5. To retrieve the sixth through tenth items, you would specify offset=5 and count=5.
  • If you omit the offset parameter, the returned list starts with the item at offset zero.
  • If you specify an offset that is greater than or equal to the number of items in the complete list, no items are returned.
  • If you omit the count parameter, the returned list includes all items starting from the offset and continuing through the end of the complete list.
  • If you specify a count that is greater than the number of items remaining in the complete list after the offset, the returned list includes all items starting from the offset and continuing through the end of the complete list.
  • If an item is deleted while you are paging through the applicable list, the full list of items returned may be incomplete. For example, suppose a tenant has six namespaces (A, B, C, D, E, and F):
    1. You issue a GET request for the namespaces resource with these query parameters: offset=0&count=3

      HCP returns A, B, and C.

    2. Namespace B is deleted without your knowledge.

      The remaining namespaces are A, C, D, E, and F.

    3. You issue a second GET request for the namespaces resource with these query parameters: offset=3&count=3

      HCP returns E and F. It does not return D because D is now at offset two.

  • You can page, sort, and filter resource lists in the same request.
TipBy default, resource lists are returned in an arbitrary order, and the order may not be the same if the request is issued more than once. To ensure that you get all the expected items when paging, specify a sort order in each request.

Sorting resource lists

You can retrieve a sorted list of items of a particular resource type by specifying the property you want to sort by and the sort order in the GET request. You can sort namespaces by name or by hard quota. You can sort user accounts by username.

To specify a sort property and sort order, you use these query parameters in the GET request:

  • sortType=property-name

    specifies the property you want to sort by. Valid values are:

    • For the namespaces and dataAccessPermissions resources, name and hardQuota
    • For the userAccounts resource, username

    This parameter is optional. For the namespaces and dataAccessPermissions resources, the default is name.

  • sortOrder=(ascending|descending)

    specifies the order in which to sort the listed items.

    This parameter is optional. The default is ascending.

For example, this GET request sorts the list of in descending order by hard quota:

curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"    "https://admin.hcp.example.com:9090/mapi/tenants/finance/namespaces?
         sortType=hardQuota&sortOrder=descending&prettyprint"

These considerations apply to sorting resource lists:

  • The sortType and sortOrder parameters are valid only with the namespaces, userAccounts, and dataAccessPermissions resources.
  • You can page, sort, and filter resource lists in the same request.

Filtering resource lists

You can retrieve a subset of items of a particular resource type by specifying a filter in the GET request. To apply a filter, you specify the property you want to filter by and the text string to use as the filter. The filtered list includes only those items for which the value of the specified property begins with or is the same as the specified text string.

You can filter namespaces by name or by tag. You can filter user accounts by username.

To specify a filter, you use these query parameters in the GET request:

  • filterType=property-name

    specifies the property by which to filter the resource list. Valid values for property-name are:

    • For the namespaces and dataAccessPermissions resources, name and tag
    • For the userAccounts resource, username

    The filterType parameter is optional. For the namespaces and dataAccessPermissions resources, the default is name.

  • filterString=text-string

    specifies the text string to use as the filter. This string is not case sensitive.

    Text strings can be at most 64 characters long and can contain any valid UTF-8 characters except commas (,). White space is allowed and must be percent encoded.

For example, this GET request filters the list of namespaces for the Finance tenant by names beginning with the string accounts:

curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces
        ?filterType=name&filterString=accounts&prettyprint"

These considerations apply to filtering resource lists:

  • The filterType and filterString parameters are valid only with the namespaces, userAccounts, and dataAccessPermissions resources.
  • If a GET request includes the filterType parameter but does not include the filterString parameter, HCP returns the complete list of items of the applicable type.
  • You can page, sort, and filter resource lists in the same request.

Replication resources

Replication resources let you configure, monitor, and manage replication. The table below provides information about these resources.

.../services/replication
Data typeMethodUseAccessNotes

replication

Service

GETRetrieve Replication service settingsSystem-level user account with the monitor or administrator role
POSTModify Replication service settings or perform an action on the Replication serviceSystem-level user account with the administrator role
.../services/replication/certificates
Data typeMethodUseAccessNotes
CertificatesGETRetrieves a list of replication certificatesSystem-level user account with the monitor or administrator role
N/APUTUploads a new replication certificateSystem-level user account with the administrator role
.../services/replication/certificates/certificate-id
Data typeMethodUseAccessNotes
TextGETRetrieve information about a replication certificateSystem-level user account with the monitor or administrator role
N/ADELETEDelete a replication certificateSystem-level user account with the administrator role
.../services/replication/certificates/server
Data typeMethodUseAccessNotes
TextGETDownloads the replication server certificate and saves it on your computer as a server_certificate.txt fileSystem-level user account with the administrator role
.../services/replication/links
Data typeMethodUseAccessNotes
linkPUTCreate a replication linkSystem-level user account with the administrator role
ListGETRetrieve a list of the replication links in which the HCP system being queried participatesSystem-level user account with the monitor or administrator role

The listed replication links are identified by link name.

In XML, the element that identifies each link is name. The root element for the list of links is links.

In JSON, the name in the name/value pair that lists the links is name.

.../services/replication/links/link-name
Data typeMethodUseAccessNotes
linkGETRetrieve information about a replication linkSystem-level user account with the monitor or administrator role
N/AHEADCheck for the existence of a replication linkSystem-level user account with the monitor or administrator role
linkPOSTModify or perform an action on a replication linkSystem-level user account with the administrator role
N/ADELETEDelete a replication linkSystem-level user account with the administrator role
.../services/replication/links/link-name/content
Data typeMethodUseAccessNotes
contentGETRetrieve a list of the items included in a replication linkSystem-level user account with the monitor or administrator role
.../services/replication/links/link-name/content/defaultNamespaceDirectories
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the default-namespace directories included in a replication linkSystem-level user account with the monitor or administrator role

This resource is available only if the default tenant exists.

The listed directories are identified by directory name.

In XML, the element that identifies each directory is name. The root element for the list of directories is defaultNamespace-Directories.

In JSON, the name in the name/value pair that lists the directories is name.

.../services/replication/links/link-name/content/defaultNamespaceDirectories/directory-name
Data typeMethodUseAccessNotes
N/APUTAdd a default-namespace directory to a replication linkSystem-level user account with the administrator role
DELETERemove a default-namespace directory from a replication linkSystem-level user account with the administrator role
.../services/replication/links/link-name/content/chainedLinks
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the chained links included in an active/passive linkSystem-level user account with the monitor or administrator role

Not valid for active/active links.

The listed chained links are identified by link name.

In XML, the element that identifies each chained link is name. The root element of the list of chained links is chainedLinks.

In JSON, the name in the name/value pair that lists the chained links is name.

This resource is not valid for active/active links.

.../services/replication/links/link-name/content/chainedLinks/link-name
Data typeMethodUseAccessNotes
N/APUTAdd a chained link to an active/passive linkSystem-level user account with the administrator roleYou cannot add a chained link to an active/active link.
DELETERemove a chained link from an active/passive linkSystem-level user account with the administrator role
.../services/replication/links/link-name/content/tenants
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the HCP tenants included in a replication linkSystem-level user account with the monitor or administrator role

The listed tenants are identified by tenant name.

In XML, the element that identifies each tenant is name. The root element for the list of tenants is tenants.

In JSON, the name in the name/value pair that lists the tenants is name.

.../services/replication/links/link-name/content/tenants/tenant-name
Data typeMethodUseAccessNotes
N/APUTAdd an HCP tenant to a replication linkSystem-level user account with the administrator role

tenant

(data type for replication link content tenant)

GETRetrieve replication status information for a tenant included in a replication linkSystem-level user account with the monitor or administrator role
N/APOSTPerform an action on a tenant included in a replication linkSystem-level user account with the administrator role
DELETERemove an HCP tenant from a replication linkSystem-level user account with the administrator role
.../services/replication/links/link-name/localCandidates
Data typeMethodUseAccessNotes
contentGETRetrieve a list of the items on the system being queried that are eligible to be included in a replication linkSystem-level user account with the monitor or administrator role
.../services/replication/links/link-name/localCandidates/defaultNamespaceDirectories
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the default-namespace directories on the system being queried that are eligible to be included in a a replication linkSystem-level user account with the monitor or administrator role

This resource is available only if the default tenant exists.

The listed directories are identified by directory name.

In XML, the element that identifies each directory is name. The root element for the list of directories is defaultNamespace-Directories.

In JSON, the name in the name/value pair that lists the directories is name.

.../services/replication/links/link-name/localCandidates/chainedLinks
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the inbound links on the system being queried that are eligible to be included in an active/passive linkSystem-level user account with the monitor or administrator role

Not valid for active/active links.

The listed chained links are identified by link name.

In XML, the element that identifies each chained link is name. The root element of the list of chained links is chainedLinks.

In JSON, the name in the name/value pair that lists the chained links is name.

This resource is not valid for active/active links.

.../services/replication/links/link-name/localCandidates/tenants
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the HCP tenants on the system being queried that are eligible to be included in a replication linkSystem-level user account with the monitor or administrator role

The listed tenants are identified by tenant name.

In XML, the element that identifies each tenant is name. The root element of the list of tenants is tenants.

In JSON, the name in the name/value pair that lists the tenants is name.

.../services/replication/links/link-name/remoteCandidates
Data typeMethodUseAccessNotes
contentGETRetrieve a list of the items on the other system involved in a replication link that are eligible to be included in the linkSystem-level user account with the monitor or administrator role
.../services/replication/links/link-name/remoteCandidates/defaultNamespaceDirectories
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the default-namespace directories on the other system involved in a replication link that are eligible to be included in the linkSystem-level user account with the monitor or administrator role

This resource is available only if the default tenant exists.

The listed directories are identified by directory name.

In XML, the element that identifies each directory is name. The root element of the list of directories is defaultNamespace-Directories.

In JSON, the name in the name/value pair that lists the directories is name.

.../services/replication/links/link-name/remoteCandidates/chainedLinks
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the inbound links on the other system involved in an active/passive link that are eligible to be included in the linkSystem-level user account with the monitor or administrator role

Not valid for active/active links.

The listed chained links are identified by link name.

In XML, the element that identifies each chained link is name. The root element of the list of chained links is chainedLinks.

In JSON, the name in the name/value pair that lists the chained links is name.

This resource is not valid for active/active links.

.../services/replication/links/link-name/remoteCandidates/tenants
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the HCP tenants on the other system involved in a replication link that are eligible to be included in the linkSystem-level user account with the monitor or administrator role

The listed tenants are identified by directory name.

In XML, the element that identifies each tenant is name. The root element of the list of tenants is tenants.

In JSON, the name in the name/value pair that lists the tenants is name.

.../services/replication/links/link-name/schedule
Data typeMethodUseAccessNotes
scheduleGETRetrieve the schedules for an active/active link or the schedule for an active/passive linkSystem-level user account with the monitor or administrator role
POSTModify the schedules for an active/active link or the schedule for an active/passive linkSystem-level user account with the administrator role

Example: Creating a replication link

Here’s a sample PUT request that creates an active/active link named MA-CA between the local HCP system, hcp-ma.example.com, and a remote HCP system named hcp-ca.example.com. The link definition is in an XML file named MA-CA.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<link>
    <name>MA-CA</name>
    <description>Active/active link between systems in MA and CA</description>
    <type>ACTIVE_ACTIVE</type>
    <connection>
         <remoteHost>replication.admin.hcp-ca.example.com</remoteHost>
    </connection>
    <compression>false</compression>
    <encryption>false</encryption>
    <priority>OLDEST_FIRST</priority>
    <failoverSettings>
         <local>
             <autoFailover>true</autoFailover>
             <autoFailoverMinutes>60</autoFailoverMinutes>
         </local>
         <remote>
             <autoFailover>true</autoFailover>
             <autoFailoverMinutes>60</autoFailoverMinutes>
         </remote>
    </failoverSettings>
</link>
Request with cURL command line
curl -k -iT MA-CA.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp-ma.example.com:9090/mapi/services/replication/links"
Request in Python using PycURL
import pycurl
import os
filehandle = open("MA-CA.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-ma.example.com:9090/mapi/services/" +
  "replication/links")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("MA-CA.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/services/replication/links HTTP/1.1
Host: admin.hcp-ma.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 648
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving a replication certificate

Here's a sample GET request that retrieves a replication certificate from the HCP system. The request is made using a system-level user account that includes the administrator or monitor role.

Request with cURL command line
curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/services/replication/certificates
        ?prettyprint"
Request in Python using PycURL
import pycurl
filehandle = open("certificates.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090
  /mapi/services/replication/certificates")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/services/replication/cerificates HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 329
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<certificates>
    <certificate>
        <expiresOn>2021-12-12T15:35:10-0500</expiresOn>
        <id>server</id>
        <subjectDN>CN=*.example.com, OU=HCP, O=Hitachi, L=Waltham, ST=Massachusetts, C=US</subjectDN>
        <validOn>2016-12-12T15:35:10-0500</validOn>
    </certificate>
</certificates>

Example: Adding a replication certificate

Here's a sample PUT request that uploads a replication certificate to the HCP system. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -iT certificate.txt
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/services/replication/certificates"
Request in Python using PycURL
import pycurl

filehandle = open("certificate.txt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/" +
  "services/replication/certificates")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/services/replication/certificates HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 1396
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
Expires: Thu, 01 Jan 1970 00:00:00 GMT
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving a list of eligible local candidates

Here’s a sample GET request that retrieves a list of the HCP tenants and default-namespace directories on the local system, hcp-ma.example.com, that are eligible to be included in the active/active replication link named MA-CA. The request writes the list of local candidates to a file named local-candidates.xml. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -i -H "Accept: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp-ma.example.com:9090/mapi/services/replication/links/
         MA-CA/localCandidates?prettyprint" > local-candidates.xml
Request in Python using PycURL
import pycurl
filehandle = open("local-candidates.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-ma.example.com:9090/mapi/services/" +
  "replication/links/MA-CA/localCandidates?prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/services/replication/links/MA-CA/localCandidates?prettyprint HTTP/1.1
Host: admin.hcp-ma.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 330
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<content>
    <defaultNamespaceDirectories>
        <name>brochures_2015</name>
        <name>brochures_2016</name>
        <name>brochures_2017</name>
    </defaultNamespaceDirectories>
    <tenants>
        <name>Finance</name>
        <name>HR</name>
        <name>Sales-Mktg</name>
    </tenants>
</content>

Example: Adding an HCP tenant to a replication link

Here’s a sample PUT request that adds the tenant named Finance to the replication link named MA-CA. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp-ma.example.com:9090/mapi/services/replication/links/
         MA-CA/content/tenants/Finance"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-ma.example.com:9090/mapi/" +
  "services/replication/links/4-3/content/tenants/LisaTenant-2")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "PUT")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
PUT /mapi/services/replication/links/MA-CA/content/tenants/Finance HTTP/1.1
Host: admin.hcap-ma.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Setting the schedule for a replication link

Here’s the a sample POST request that sets the local and remote schedules for an active/active link named MA-CA. The new schedule is in an XML file named schedule_MA-CA.xml. The request is made using a system-level user account that includes the administrator role.

Request body in XML
<schedule>
    <local>
        <scheduleOverride>NONE</scheduleOverride>
        <transition>
            <time>Sun:00</time>
             <performanceLevel>HIGH</performanceLevel>
        </transition>
        <transition>
            <time>Sun:06</time>
            <performanceLevel>MEDIUM</performanceLevel>
        </transition>
        <transition>
             <time>Sat:00</time>
             <performanceLevel>HIGH</performanceLevel>
        </transition>
        <transition>
             <time>Sat:06</time>
             <performanceLevel>MEDIUM</performanceLevel>
        </transition>
    </local>
    <remote>
        <scheduleOverride>NONE</scheduleOverride>
        <transition>
             <time>Sun:00</time>
             <performanceLevel>HIGH</performanceLevel>
        </transition>
        <transition>
             <time>Mon:00</time>
             <performanceLevel>MEDIUM</performanceLevel>
        </transition>
    </remote>
</schedule>
Request with cURL command line
curl -k -i -d @schedule_MA-CA.xml
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp-ma.example.com:9090/mapi/services/replication/links/
         MA-CA/schedule"
Request in Python using PycURL
import pycurl
import os
filehandle = open("schedule_MA-CA.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-ma.example.com:9090/mapi/services/" +
  "replication/links/MA-CA/schedule")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
  os.path.getsize("schedule_MA-CA.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/services/replication/links/MA-CA/schedule HTTP/1.1
Host: admin.hcp-ma.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 807
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Failing over a replication link

Here’s a sample POST request that fails over the link named MA-CA to the local system, hcp-ca.example.com. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -iX POST
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp-ca.example.com:9090/mapi/services/replication/links/
         MA-CA?failOver"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp-ca.example.com:9090/mapi/services/" +
  "replication/links/MA-CA?failOver")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
POST /mapi/services/replication/links/MA-CA?failOver HTTP/1.1
Host: admin.hcp-ca.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Retention class resources

Retention class resources let you create, retrieve information about, modify, and delete retention classes. The tables below provides information about these resources.

.../tenants/tenant-name/namespaces/namespace-name/retentionClasses
Data typeMethodUseAccessNotes
retentionClassPUTCreate a retention class for a namespace
  • For an HCP namespace, tenant-level user account with the compliance role
  • For the default namespace, system-level user account with the compliance role
ListGETRetrieve a list of the retention classes defined for a namespace
  • For an HCP namespace, tenant-level user account with the monitor, administrator, or compliance role
  • For the default namespace, system-level user account with the monitor, administrator, or compliance role

The listed retention classes are identified by retention class name.

In XML, the element that identifies each retention class is name. The root element for the list of retention classes is retentionClasses.

In JSON, the name in the name/value pair that lists the retention classes is name.

.../tenants/tenant-name/namespaces/namespace-name/retentionClasses/retention-class-name
Data typeMethodUseAccessNotes
retentionClassGETRetrieve information about a retention class
  • For an HCP namespace, tenant-level user account with the monitor, administrator, or compliance role
  • For the default namespace, system-level user account with the monitor, administrator, or compliance role
N/AHEADCheck for the existence of a retention class
  • For an HCP namespace, tenant-level user account with the monitor, administrator, or compliance role
  • For the default namespace, system-level user account with the monitor, administrator, or compliance role
retentionClassPOSTModify a retention class
  • For an HCP namespace, tenant-level user account with the compliance role
  • For the default namespace, system-level user account with the compliance role
N/ADELETEDelete a retention class
  • For an HCP namespace, tenant-level user account with the compliance role
  • For the default namespace, system-level user account with the compliance role
You can delete a retention class only if the namespace is in enterprise mode.

Example: Creating a retention class

Here’s a sample PUT request that creates a retention class named FN-Std-42 for the Accounts-Receivable namespace. The retention class is defined in an XML file named RC-FN-Std-42.xml. The request is made using a tenant-level user account that includes the compliance role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retentionClass>
    <name>FN-Std-42</name>
    <description>Implements Finance department standard #42 - keep for 10
         years.</description>
    <value>A+10y</value>
    <allowDisposition>true</allowDisposition>
</retentionClass>
Request with cURL command line
curl -k -iT RC-FN-Std-42.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
         accounts-receivable/retentionClasses"
Request in Python using PycURL
import pycurl
import os
filehandle = open("RC-FN-Std-42.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "namespaces/accounts-receivable/retentionClasses")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("RC-FN-Std-42.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants/finance/namespaces/accounts-receivable/retentionClasses
    HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb
Content-Type: application/xml
Content-Length: 275
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Retrieving a list of retention classes

Here’s a sample GET request that retrieves a list of the retention classes defined for the Accounts-Receivable namespace. The request writes the list of retention classes to a file named AR-retclasses.xml. The request is made using a tenant-level user account that includes the compliance role.

Request with cURL command line
curl -k -H "Accept: application/xml"
    -H "Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
         accounts-receivable/retentionClasses?prettyprint" > AR-retclasses.xml
Request in Python using PycURL
import pycurl
filehandle = open("AR-retclasses.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "namespaces/accounts-receivable/retentionClasses?prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/tenants/finance/namespaces/accounts-receivable/retentionClasses
    ?prettyprint HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bXdoaXRl:ad49ce36d0cec9634ef63b24151be0fb
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 136
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retentionClasses>
    <name>FN-Std-37</name>
    <name>FN-Std-42</name>
</retentionClasses>

Service statistics resource

The service statistics resource lets you retrieve the statistical information of services used by your HCP system.

NoteA best practice is to limit your HTTP GET requests for retrieving statistics and metrics to once per hour. Polling the system more frequently can lead to system instability.
.../services/statistics
Data typeMethodUseAccessNotes
serviceStatisticsGETRetrieve the statistics of services used by the HCP systemSystem-level user with the administrator or monitor role.

Example: Retrieving service statistics

Here is a sample request that retrieves service statistics for a system. In this example, statistics are collected on a service that is running, a service that is ready to run, and a service that is currently disabled.

Request with cURL command line
curl -ik -H "Authorization: HCP ZGVa3b9c17d52107f34fhdb83c7a5" -H "Accept: application/xml" "https://admin.hcp.example.com:9090/mapi/services/statistics?prettyprint"
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<serviceStatistics>
     <requestTime>1524773822369</requestTime>
     <services>
          <service>
               <name>StorageTieringService</name>
               <state>RUNNING</state>
               <startTime>1564040581</startTime>
               <formattedStartTime>7/25/2019 3:43:01 EDT</formattedStartTime>
               <endTime>-1</endTime>
               <performanceLevel>HIGH</performanceLevel>
               <objectsExamined>1056</objectsExamined>
               <objectsExaminedPerSecond>1056.0</objectsExaminedPerSecond>
               <objectsServiced>0</objectsServiced>
               <objectsServicedPerSecond>0.0</objectsServicedPerSecond>
               <objectsUnableToService>0</objectsUnableToService>
               <objectsUnableToServicePerSecond>0.0</objectsUnableToServicePerSecond>
          </service>
          <service>
               <name>GarbageCollection</name>
               <state>READY</state>
               <startTime>1539531912</startTime>
               <formattedStartTime>7/25/2019 0:00:00 EST</formattedStartTime>
               <endTime>1539576002</endTime>
               <formattedEndTime>7/25/2019 0:04:49 EST</formattedEndTime>
               <objectsExamined>29530</objectsExamined>
               <objectsExaminedPerSecond>1102.05</objectsExaminedPerSecond>
               <objectsServiced>27570</objectsServiced>
               <objectsServicedPerSecond>.08</objectsServicedPerSecond>
               <objectsUnableToService>0</objectsUnableToService>
               <objectsUnableToServicePerSecond>0.0</objectsUnableToServicePerSecond>
          </service>
          <service>
               <name>RetirementPolicy</name>
               <state>DISABLED</state>
               <startTime>-1</startTime>
               <formattedStartTime>-1</formattedStartTime>
               <endTime>-1</endTime>
               <formattedEndTime>-1</formattedEndTime>
               <objectsExamined>0</objectsExamined>
               <objectsExaminedPerSecond>0.0</objectsExaminedPerSecond>
               <objectsServiced>0</objectsServiced>
               <objectsServicedPerSecond>0.0</objectsServicedPerSecond>
               <objectsUnableToService>0</objectsUnableToService>
               <objectsUnableToServicePerSecond>0.0</objectsUnableToServicePerSecond>
          </service>
     </services>
<serviceStatistics>

Support access credentials resource

Use the Support access credentials resource to retrieve current Hitachi Vantara Support access credentials and to configure exclusive Support access credentials for additional security compliance.

Note
  • To retrieve Support access credentials for an HCP system, a system-level user account with the monitor, administrator, security, or service role is required.
  • To configure exclusive Hitachi Vantara Support access credentials for an HCP system, a system-level user account with the administrator or service role is required.
.../supportaccesscredentials
Data typeMethodUseAccessNotes
supportAccessCredentialsGETRetrieve the currently configured Support access credentials. System-level user with the monitor,administrator, security, or service role.
PUTConfigure exclusive Support access credentials by uploading the exclusive Hitachi Vantara Support access credentials package to the HCP system.System-level user with the administrator or service role.
Example: Retrieving information about Support access credentials when exclusive Support access credentials are installed

Here is a sample GET request that retrieves information about the currently configured exclusive Hitachi Vantara Support access credentials on the HCP system.

Request using the cURL command line:

curl -i -k  -b hcp-api-auth="c2VjdXJpdHk=:a3b9c163f6c520407ff34cfd"
 https://172.18.150.236:9090/mapi/supportaccesscredentials?prettyprint

Response body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <supportAccessCredentials>
          <applyTimeStamp>1599143327</applyTimeStamp>
          <createTimeStamp>1597699675</createTimeStamp>
          <type>Exclusive</type>
          <defaultKeyType>Arizona</defaultKeyType>
          <serialNumberFromPackage>425999</serialNumberFromPackage>
     </supportAccessCredentials>
Example: Retrieving information about Support access credentials when the default Support access credentials are installed

Here is a sample GET request that retrieves information about the currently configured default Hitachi Vantara Support access credentials.

Request using the cURL command line:

curl -i -k  -b hcp-api-auth="c2VjdXJpdHk=:a3b9c163f6c520407ff34cfd"
 https://172.18.150.236:9090/mapi/supportaccesscredentials?prettyprint

Response body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
     <supportAccessCredentials>
          <type>Default</type>
          <defaultKeyType>Arizona</defaultKeyType>
     </supportAccessCredentials>
Example: Updating Support access credentials to exclusive Hitachi Vantara Support access

Here is a sample PUT request that updates the Support access credentials on an HCP system to exclusive Hitachi Vantara Support access by uploading an SSH key from the Exclusive Hitachi Vantara Support Access Credentials package.

Request using the cURL command line:

curl -i -k -T HCP-SSHKeyPackage-04022020_14-58-20.plk
 -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
 https://admin.hcp.example.com:9090/mapi/supportAccesscredentials

Response header:

Response header:HTTP/1.1 200 OK
Content-Type: application/xml
Expires: Thu, 07 Oct 2021 00:00:00 GMT
X-HCP-SoftwareVersion: 9.2.0.251
Content-Length: 0

System-level group account resources

System-level group account resources let you retrieve information about the system-level group accounts. The tables below provide information about these resources.

.../groupAccounts
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the system-level group accounts.System-level user account with the monitor, administrator, or security role

The listed group accounts are identified by the group name.

In XML, the element that identifies each group account is groupname. The root element for the list of group accounts is groupAccounts.

In JSON, the name in the name/value pair that lists the group accounts is groupname.

.../groupAccounts/group-name
Data typeMethodUseAccessNotes
groupAccountGETRetrieve information about a group account.System-level user account with the monitor, administrator, or security roleThe information returned depends on the roles associated with the user making the request.
N/AHEADCheck for the existence of a group account.System-level user account with the monitor, administrator, or security role

Example: Retrieving system-level group accounts

Here is a sample GET request that retrieves a list of system-level group accounts. The request writes the list of group accounts to a file named systemLevelGroups.xml. The request is made with a system-level user account that includes the monitor role.

Request with cURL command line
curl -k -i -H "Authorization: bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp.example.com:9090/mapi/groupAccounts?verbose=true&
     prettyprint" >systemLevelGroups.xml
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groupAccounts>
    <groupname>Admins@dev.hcp.example.com</groupname>
    <groupname>Admins@finance.hcp.example.com</groupname>
    <groupname>Admins@sales.hcp.example.com</groupname>
</groupAccounts>

Example: Retrieving system-level group account information

Here is a sample GET request that retrieves the system-level group account information for the groupname Admins@dev.hcp.example.com. The request writes the group account information to a file named systemLevelGroup-Admins-dev-hcp-ex.xml. The request is made with a system-level user account that includes the monitor role.

Request with cURL command line
curl -k -i -H "Authorization: bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp.example.com:9090/mapi/groupAccounts/
    Admins@dev.hcp.example.com?verbose=true&prettyprint" >
    systemLevelGroup-Admins-dev-hcp-ex.xml
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groupAccount>
    <allowNamespaceManagement>false</allowNamespaceManagement>
    <externalGroupID>S-1-2-34-123456789-1234567890-1234567890-
       1234<externalGroupID>
    <groupname>Admins@dev.hcp.example.com</groupname>
    <roles>
        <role>SEARCH</role>
        <role>MONITOR</role>
        <role>SERVICE</role>
        <role>COMPLIANCE</role>
    <roles>
</groupAccount>

System-level user account resources

The system-level user account resources let you retrieve a list of the system-level user accounts, retrieve information about a system-level user account, and change the password for a locally authenticated system-level user account. The table below provides information about these resources.

.../userAccounts
Data TypeMethodUseAccessNotes
ListGETRetrieve a list of the system-level user accounts.System-level user account with the monitor, administrator, or security role

The listed user accounts are identified by the account username.

In XML, the element that identifies each user account is username. The root element for the list of user accounts is userAccounts.

In JSON, the name in the name/value pair that lists the user accounts is username.

.../userAccounts/username
Data TypeMethodUseAccessNotes
userAccountGETRetrieve information about a system-level user account.System-level user account with the monitor, administrator, or security role
N/AHEADCheck for the existence of a user account.System-level user account with the monitor, administrator, or security role
N/APOSTChange the password for a locally authenticated system-level user account.System-level user account with the security roleThe required query parameter for changing user account passwords is password=password.
.../userAccounts/username/changePassword
Data TypeMethodUseAccessNotes
updatePasswordRequestPOSTChange the password for a locally authenticated system-level user account.System-level user account with the security role

Example: Retrieving system-level user accounts

Here is a sample GET request that retrieves a list of system-level user accounts. The request writes the list of user accounts to a file named systemLevelUsers.xml. The request is made with a system-level user account that includes the monitor role.

Request with cURL command line
curl -k -i -H "Authorization: bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp.example.com:9090/mapi/userAccounts?verbose=true&
     prettyprint" > systemLevelUsers.xml
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userAccounts>
    <username>lgreen</username>
    <username>mwhite</username>
    <username>pblack</username>
</userAccounts>

Example: Retrieving system-level user account information

Here is a sample GET request that retrieves the system-level user account information for the username lgreen. The request writes the information to a file named systemLevelUser-lgreen.xml. The request is made with a system-level user account that includes the monitor role.

Request with cURL command line
curl -k -i -H "Authorization: bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp.example.com:9090/mapi/userAccounts/lgreen?verbose=true&
     prettyprint" >systemLevelUser-lgreen.xml
Response body
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userAccount>
    <enabled>true</enabled>
    <localAuthentication>true</localAuthentication>
    <roles>
        <role>ADMINISTRATOR</role>
        <role>SEARCH</role>
        <role>MONITOR</role>
        <role>SECURITY</role>
        <role>SERVICE</role>
        <role>COMPLIANCE</role>
    </roles>
    <allowNamespaceManagement>true</allowNamespaceManagement>
    <description>Developer, Team Lead</description>
    <forcePasswordChange>false</forcePasswordChange>
    <fullName>Lee Green</fullName>
    <userGUID>eaa046e0-c17e-42fb-8840-ab5e05cf8876</userGUID>
    <userID>104</userID>
    <username>lgreen</username>
</userAccount>

Example: Changing a user account password with a query parameter

Here’s a sample POST request that uses the password query parameter to change the password for the system-level user account with the username lgreen to End321!. The request is made using a system-level user account that includes the security role.

Request with cURL command line
curl -k -i -d "{}" -H "Content-Type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/userAccounts/lgreen
        ?password=End321!"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
 "https://admin.hcp.example.com:9090/mapi/" +
 "userAccounts/lgreen?password=End321!")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
POST /mapi/userAccounts/?password=End321! HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 2
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Changing a user account password in the request body

Here’s a sample POST request that uses the updatePasswordRequest data type in the request body to change the password for the system-level user account with the username lgreen. The requested new password is End321!, which is specified in an XML file named Password.xml. The request is made using a system-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<updatePasswordRequest>
    <newPassword>End321!</newPassword>
</updatePasswordRequest>
Request with cURL command line
curl -k -i -d @Password.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/userAccounts/lgreen
        /changePassword"
Request headers
POST /mapi/userAccounts/lgreen/changePassword HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 2
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Tenant resources

Tenant resources let you create, retrieve information about, modify, and delete tenants. The tables below provides information about these resources.

.../tenants/tenant-name
Data typeMethodUseAccessNotes
tenantGETRetrieve information about a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
N/AHEADCheck for the existence of a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
tenantPOSTModify a tenant
  • For an HCP tenant tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
.../tenants/tenant-name/availableServicePlans
Data typeMethodUseAccessNotes
ListGETRetrieve a list of the service plans that are available for the tenant to assign to its namespaces
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role

Valid only if the tenant is configured to allow service plan selection.

The listed service plans are identified by service plan name.

In XML, each listed service plan is the value of an element named name. In JSON, the name in the name/value pair that lists the service plans is name.

.../tenants/tenant-name/availableServicePlans/service-plan-name
Data typeMethodUseAccessNotes
available ServicePlanGETRetrieve information about a service plan that’s available for the tenant to assign to its namespaces
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
Valid only if the tenant is configured to allow service plan selection.
.../tenants/tenant-name/chargebackReport
Data typeMethodUseAccessNotes
chargeback ReportGETGenerate a chargeback report for a tenantTenant-level user account with the monitor or administrator role

Not valid for the default tenant.

Supported output formats are XML, JSON, and CSV.

.../tenants/tenant-name/consoleSecurity
Data typeMethodUseAccessNotes
consoleSecurityGETRetrieve the Tenant Management Console configuration for a tenantTenant-level user account with the security roleNot valid for the default tenant.
POSTModify the Tenant Management Console configuration for a tenantTenant-level user account with the security role
.../tenants/tenant-name/contactInfo
Data typeMethodUseAccessNotes
contactInfoGETRetrieve the contact information for a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role
POSTModify the contact information for a tenant
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
.../tenants/tenant-name/cors
Data typeMethodUseAccessNotes
corsPUTSet the default CORS rules configuration for all namespaces owned by the tenant
  • System-level user account with the administrator role
  • Tenant-level user account with the administrator role
If the default tenant-level CORS configuration is set, it is applicable for all namespaces that do not have a namespace-level CORS configuration.
GETRetrieve the default CORS configuration for all namespaces owned by the tenant
  • System-level user account with the monitor or administrator role
  • Tenant-level user account with the monitor or administrator role
DELETEDelete the default CORS configuration for all namespaces owned by the tenant
  • System-level user account with the administrator role
  • Tenant-level user account with the administrator role
If the resource does not have a default CORS configuration, the HTTP status code 404 Not Found is returned.
.../tenants/tenant-name/emailNotification
Data typeMethodUseAccessNotes
email NotificationGETRetrieve the email notification configuration for a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the with the monitor or administrator role
POSTModify the email notification configuration for a tenant
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role
.../tenants/tenant-name/namespaceDefaults
Data typeMethodUseAccessNotes
namespace DefaultsGETRetrieve the default settings for namespace creation for a tenantTenant-level user account with the monitor or administrator roleNot valid for the default tenant.
POSTModify the default settings for namespace creation for a tenantTenant-level user account with the administrator role
.../tenants/tenant-name/permissions
Data typeMethodUseAccessNotes
ListGETRetrieve the list of permissions in the data access permission mask for a tenant
  • For an HCP tenant, tenant-level user account with the monitor, administrator, or compliance role
  • For the default tenant, system-level user account with the monitor, administrator, or compliance role
ListPOSTModify the list of permissions in the data access permission mask for a tenant
  • For an HCP tenant, tenant-level user account with the administrator role
  • For the default tenant, system-level user account with the administrator role

Valid values for permissions are:

  • DELETE
  • PRIVILEGED
  • PURGE
  • READ
  • SEARCH
  • WRITE

These values are case sensitive.

The set of permissions specified in the request body replaces the set of permissions currently included in the data access permission mask for the tenant. To remove all permissions, specify an empty list.

If the set of permissions includes PURGE, delete permission is enabled automatically. If the set of permissions includes SEARCH, read permission is enabled automatically.

.../tenants/tenant-name/searchSecurity
Data typeMethodUseAccessNotes
searchSecurityGETRetrieve the Search Console configuration for a tenantTenant-level user account with the security roleNot valid for the default tenant.
searchSecurityPOSTModify the Search Console configuration for a tenantTenant-level user account with the security roleNot valid for the default tenant.
.../tenants/tenant-name/statistics
Data typeMethodUseAccessNotes
statisticsGETRetrieve statistics about the content of the namespaces owned by a tenant
  • For an HCP tenant, tenant-level user account with the monitor or administrator role
  • For the default tenant, system-level user account with the monitor or administrator role

Example: Creating an HCP tenant

Here’s a sample PUT request that creates a tenant named Finance in the HCP system named hcp.example.com. The tenant definition is in an XML file named FinanceTenant.xml. The initial user account for the tenant has a username of lgreen and a password of start123. These are specified by query parameters. The request is made using a system-level user account that includes the administrator role.

This example assumes the existence of a service plan named Short-Term-Activity.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tenant>
    <name>Finance</name>
    <systemVisibleDescription>Created for the Finance department at Example
        Company by P.D. Grey on 2/9/2017.</systemVisibleDescription>
    <hardQuota>100 GB</hardQuota>
    <softQuota>90</softQuota>
    <namespaceQuota>5</namespaceQuota>
    <authenticationTypes>
        <authenticationType>LOCAL</authenticationType>
        <authenticationType>EXTERNAL</authenticationType>
    </authenticationTypes>
    <complianceConfigurationEnabled>true</complianceConfigurationEnabled>
    <versioningConfigurationEnabled>true</versioningConfigurationEnabled>
    <searchConfigurationEnabled>true</searchConfigurationEnabled>
    <replicationConfigurationEnabled>true</replicationConfigurationEnabled>
    <erasureCodingSelectionEnabled>true</erasureCodingSelectionEnabled>
    <tags>
        <tag>Example Company</tag>
        <tag>pdgrey</tag>
    </tags>
    <servicePlanSelectionEnabled>false</servicePlanSelectionEnabled>
    <servicePlan>Short-Term-Activity</servicePlan>
    <dataNetwork>net127</dataNetwork>
    <managementNetwork>net004</managementNetwork>
</tenant>
Request with cURL command line
curl -k -iT FinanceTenant.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/tenants?username=lgreen
        &password=start123&forcePasswordChange=false"
Request in Python using PycURL
import pycurl
import os
filehandle = open("FinanceTenant.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
  "https://admin.hcp.example.com:9090/mapi/tenants?" +
  "username=lgreen&password=start123&forcePasswordChange=false")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("FinanceTenant.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants?username=lgreen&password=start123
    &forcePasswordChange=false HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 1016
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Setting Tenant Management Console security for a tenant

Here’s a sample POST request that modifies the Tenant Management Console configuration for the Finance tenant. The Console configuration information is in an XML file named FinanceMgmtConsole.xml. The request is made using a tenant-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<consoleSecurity>
    <ipSettings>
        <allowAddresses>
             <ipAddress>192.168.103.18</ipAddress>
            <ipAddress>192.168.103.24</ipAddress>
             <ipAddress>192.168.103.25</ipAddress>
        </allowAddresses>
        <denyAddresses/>
        <allowIfInBothLists>false</allowIfInBothLists>
    </ipSettings>
    <minimumPasswordLength>6</minimumPasswordLength>
    <forcePasswordChangeDays>45</forcePasswordChangeDays>
    <disableAfterAttempts>3</disableAfterAttempts>
    <disableAfterInactiveDays>30</disableAfterInactiveDays>
    <logoutOnInactive>20</logoutOnInactive>
    <loginMessage/>
</consoleSecurity>
Request with cURL command line
curl -k -i -d @FinanceMgmtConsole.xml
    -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/consoleSecurity"
Request in Python using PycURL
import pycurl
import os
filehandle = open("FinanceMgmtConsole.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "consoleSecurity")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
  os.path.getsize("FinanceMgmtConsole.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/tenants/finance/consoleSecurity HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 620
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Generating a chargeback report for a tenant

Here’s a sample GET request that generates a chargeback report for the tenant named europe that has two namespaces, finance and hr. The report covers one day. The report is written in CSV format to a file named FinanceStats-2020-01-31.txt. The request is made using a tenant-level user account that includes the administrator role.

Request with cURL command line
curl -k -i -H "Accept: text/csv"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/
         chargebackReport?start=2020-01-31T00:00:00-0500
         &end=2020-01-31T13:59:59-0500&granularity=day"
    > FinanceStats-2020-01-31.txt
Request in Python using PycURL
import pycurl
filehandle = open("FinanceStats-2020-01-31.txt", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: text/csv",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "chargebackReport?start=2020-01-31T00:00:00-0500" +
  "&end=2020-01-31T13:59:59-0500&granularity=day")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/tenants/finance/chargebackReport?start=2017-02-17T00:00:00-0500&end=2020-01-31T23:59:59-0500&granularity=day HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Accept: text/csv
Response headers
HTTP/1.1 200 OK
Content-Type: text/csv
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 767
Response body
systemName,tenantName,namespaceName,startTime,endTime,objectCount,ingestedVolume,storageCapacityUsed,bytesIn,bytesOut,reads,writes,deletes,multipartObjects,multipartObjectParts,multipartObjectBytes,multipartUploads,multipartUploadParts,multipartUploadBytes,deleted,valid
finance.hcp.example.com,europe,finance,2017-02-17T00:00:00-0500,2017-02-17T23:59:59-0500,6,134243721,134270976,123986263,87561,1,10,0,2,7,93213889,0,0,0,false,true
finance.hcp.example.com,europe,hr,2017-02-17T00:00:00-0500,2017-02-17T23:59:59-0500,7,9609368,9621504,9609368,0,0,7,0,0,0,0,0,0,0,false,true
finance.hcp.example.com,europe,,2017-02-17T00:00:00-0500,2017-02-17T23:59:59-0500,13,143853089,143892480,133595631,87561,1,17,0,2,7,93213889,0,0,0,false,true

Tenant-level group account resources

Tenant-level group account resources let you create, retrieve information about, modify, and delete tenant-level group accounts. The table below provides information about these resources.

Group account resources are not available for the default tenant.

.../tenants/tenant-name/groupAccounts
Data typeMethodUseAccessNotes
groupAccountPUTCreate a group account for a tenantTenant-level user account with the security roleYou can create a group account only if HCP is configured to support AD.
ListGETRetrieve a list of the group accounts defined for a tenantTenant-level user account with the monitor, administrator, or security role

The listed group accounts are identified by the group name.

In XML, the element that identifies each group account is groupname. The root element for the list of group accounts is groupAccounts.

In JSON, the name in the name/value pair that lists the group accounts is groupname.

.../tenants/tenant-name/groupAccounts/group-name
Data typeMethodUseAccessNotes
groupAccountGETRetrieve information about a group accountTenant-level user account with the monitor, administrator, or security roleThe information returned depends on the roles associated with the user making the request.
N/AHEADCheck for the existence of a group accountTenant-level user account with the monitor, administrator, or security role
groupAccountPOSTModify a group accountTenant-level user account with the administrator or security roleA user with only the administrator role can modify only the allow-NamespaceManagement property. A user with only the security role cannot modify that property.
N/ADELETEDelete a group accountTenant-level user account with the security role
.../tenants/tenant-name/groupAccounts/group-name/dataAccessPermissions
Data typeMethodUseAccessNotes

dataAccess

Permissions

GETRetrieve information about the data access permissions associated with a group accountTenant-level user account with the administrator, security, or monitor role
POSTModify the data access permissions associated with a group accountTenant-level user account with the administrator role

The request body must contain all permissions granted for each included namespace. If a namespace is not included, its permissions are not changed by the POST request.

By default, when you create a group account, it does not include any data access permissions.

Example: Creating a group account

Here’s a sample PUT request that creates a group account for the Finance tenant. The account is defined in an XML file named admin-GA.xml. The name of the group account is specified in the XML file. For the request to be successful, a group with this name must already exist in AD. The request is made using a tenant-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groupAccount>
    <groupname>hcp-admin@ad.example.com</groupname>
    <roles>
         <role>MONITOR</role>
         <role>ADMINISTRATOR</role>
    </roles>
</groupAccount>
Request with cURL command line
curl -k -iT admin-GA.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/groupAccounts"
Request in Python using PycURL
import pycurl
import os
filehandle = open("admin-GA.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "groupAccounts")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("admin-GA.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants/finance/groupAccounts HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 365
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example Retrieving group accounts

Here’s a sample GET request that retrieves all the group accounts defined for the Finance tenant. The request writes the list of group accounts to a file named finance-groups.xml. The request is made using a tenant-level user account that includes the security role.

Request with cURL command line
curl -k -H "Accept: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/groupAccounts
         ?prettyprint" > finance-groups.xml
Request in Python using PycURL
import pycurl
filehandle = open("finance-groups.xml", 'wb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Accept: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "groupAccounts?prettyprint")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.WRITEFUNCTION, filehandle.write)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
GET /mapi/tenants/groupAccounts?prettyprint HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Accept: application/xml
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 307
Response body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<groupAccounts>
    <groupname>hcp-admin@ad.example.com</groupname>
    <groupname>hcp-security@ad.example.com</groupname>
    <groupname>hcp-compliance@ad.example.com</groupname>
    <groupname>AR-read@ad.example.com</groupname>
    <groupname>AR-full-access@ad.example.com</groupname>
    <groupname>AP-read@ad.example.com</groupname>
    <groupname>AP-full-access@ad.example.com</groupname>
</groupAccounts>

Tenant-level user account resources

Tenant-level user account resources let you create, retrieve information about, modify, and delete tenant-level user accounts. The table below provides information about these resources.

User account resources are not available for the default tenant.

.../tenants/tenant-name/userAccounts
Data typeMethodUseAccessNotes
userAccountPUTCreate a user account for a tenantTenant-level user account with the security role
ListGETRetrieve a list of the user accounts defined for a tenantTenant-level user account with the monitor, administrator, or security role

The listed user accounts are identified by the account username.

In XML, the element that identifies each user account is username. The root element for the list of user accounts is userAccounts.

In JSON, the name in the name/value pair that lists the user accounts is username.

.../tenants/tenant-name/userAccounts/username
Data typeMethodUseAccessNotes
userAccountGETRetrieve information about a user accountTenant-level user account with the monitor, administrator, or security roleThe information returned depends on the roles associated with the user making the request.
N/AHEADCheck for the existence of a user accountTenant-level user account with the monitor, administrator, or security role
userAccountPOSTModify a user accountTenant-level user account with the administrator or security role

A user with only the administrator role can modify only the allow-NamespaceManagement property. A user with only the security role cannot modify that property.

N/ADELETEDelete a user accountTenant-level user account with the security role
.../tenants/tenant-name/userAccounts/username/changePassword
Data typeMethodUseAccessNotes
updatePassword RequestPOSTChange the password for a locally authenticated tenant-level user accountSystem-level user account with the security role or tenant-level user account with the security role
.../tenants/tenant-name/userAccounts/username/dataAccessPermissions
Data typeMethodUseAccessNotes
dataAccess PermissionsGETRetrieve information about the data access permissions associated with a user accountTenant-level user account with the administrator or security role
POSTModify the data access permissions associated with a user accountTenant-level user account with the administrator role

The request body must contain all permissions granted for each included namespace. If a namespace is not included, its permissions are not changed by the POST request.

By default, when you create a user account, it does not include any data access permissions.

Example: Creating a user account

Here’s a sample PUT request that creates a user account for the Finance tenant. The account is defined in an XML file named mwhite-UA.xml. The username for the account is specified in the XML file. The password is specified by the password query parameter. The request is made using a tenant-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userAccount>
    <username>mwhite</username>
    <fullName>Morgan White</fullName>
    <description>Compliance officer.</description>
    <localAuthentication>true</localAuthentication>
    <forcePasswordChange>true</forcePasswordChange>
    <enabled>true</enabled>
    <roles>
         <role>COMPLIANCE</role>
         <role>MONITOR</role>
    </roles>
    <allowNamespaceManagement>false</allowNamespaceManagement>
</userAccount>
Request with cURL command line
curl -k -iT mwhite-UA.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/userAccounts
         ?password=start123"
Request in Python using PycURL
import pycurl
import os
filehandle = open("mwhite-UA.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "userAccounts?password=start123")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("mwhite-UA.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
PUT /mapi/tenants/finance/userAccounts?password=start123 HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 365
Response headers
HTTP/1.1 200 OK
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Changing the roles associated with a user account

Here’s a sample POST request that changes the roles associated with the user account with the username mwhite. The new set of roles is specified in an XML file named mwhite-UAroles.xml. The request is made using a tenant-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<userAccount>
    <roles>
         <role>COMPLIANCE</role>
         <role>MONITOR</role>
         <role>ADMINISTRATOR</role>
    </roles>
</userAccount>
Request with cURL command line
curl -k -i -d @mwhite-UAroles.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/
         userAccounts/mwhite"
Request in Python using PycURL
import pycurl
import os
filehandle = open("mwhite-UAroles.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "userAccounts/mwhite")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
  os.path.getsize("mwhite-UAroles.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/tenants/finance/userAccounts/mwhite HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 120
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Changing the data access permissions associated with a user account

Here’s a sample POST request that changes the data access permissions associated with the user account with the username pblack. The new set of permissions is specified in an XML file named pblack-UAperms.xml. The file includes permissions for both the Accounts-Receivable and Accounts-Payable namespaces. The request is made using a tenant-level user account that includes the administrator role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataAccessPermissions>
    <namespacePermission>
         <namespaceName>Accounts-Receivable</namespaceName>
         <permissions>
             <permission>READ</permission>
              <permission>BROWSE</permission>
              <permission>WRITE</permission>
              <permission>DELETE</permission>
              <permission>PURGE</permission>
              <permission>SEARCH</permission>
          </permissions>
     </namespacePermission>
    <namespacePermission>
         <namespaceName>Accounts-Payable</namespaceName>
       <permissions>
             <permission>READ</permission>
         </permissions>
    </namespacePermission>
</dataAccessPermissions>
Request with cURL command line
curl -k -i -d @pblack-UAperms.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/userAccounts/
         pblack/dataAccessPermissions"
Request in Python using PycURL
import pycurl
import os
filehandle = open("pblack-UAperms.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml",
  "Authorization: HCP \
  bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"])
curl.setopt(pycurl.URL,
  "https://finance.hcp.example.com:9090/mapi/tenants/finance/" +
  "userAccounts/pblack/dataAccessPermissions")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.setopt(pycurl.INFILESIZE,
   os.path.getsize("pblack-UAperms.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()
Request headers
POST /mapi/tenants/finance/userAccounts/pblack/dataAccessPermissions
    HTTP/1.1
Host: finance.hcp.example.com:9090
Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6
Content-Type: application/xml
Content-Length: 572
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Changing a user account password in the request body

Here’s a sample POST request that uses the updatePasswordRequest data type in the request body to change the password for a Finance tenant user account with the username lgreen . The requested new password is End321!, which is specified in an XML file named Password.xml. The request is made using a system-level user account that includes the security role.

Request body in XML
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<updatePasswordRequest>
    <newPassword>End321!</newPassword>
</updatePasswordRequest>
Request with cURL command line
curl -k -i -d @Password.xml -H "Content-Type: application/xml"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/tenants/finance
        /userAccounts/lgreen/changePassword"
Request headers
POST /mapi/tenants/finance/userAccounts/lgreen/changePassword HTTP/1.1
Host: admin.hcp.example.com:9090
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/xml
Content-Length: 2
Response headers
HTTP/1.1 200 OK
Content-Type: application/xml
X-HCP-SoftwareVersion: 9.0.0.2
Content-Length: 0

Example: Resetting the security user passwords for a tenant

Here’s a sample POST request that resets the passwords for the tenant named Finance to start123. The empty request body has a content type of JSON. The request is made using a system-level user account that includes the administrator role.

Request with cURL command line
curl -k -i -d "{}" -H "Content-Type: application/json"
    -H "Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"
    "https://admin.hcp.example.com:9090/mapi/tenants/finance/userAccounts
        ?resetPasswords=start123"
Request in Python using PycURL
import pycurl
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP \
    YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382"])
curl.setopt(pycurl.URL,
    "https://admin.hcp-ca.example.com:9090/mapi/tenants/finance/" +
    "userAccounts?resetPasswords=start123")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.CUSTOMREQUEST, "POST")
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
Request headers
POST /mapi/tenants/finance/userAccounts?resetPasswords=start123 HTTP/1.1
Host: admin.hcp.example.com:9090
Accept: */*
Authorization: HCP YWxscm9sZXM=:04EC9F614D89FF5C7126D32ACB448382
Content-Type: application/json
Content-Length: 2
Response headers

HTTP/1.1 200 OKContent-Type: application/xmlX-HCP-SoftwareVersion: 9.0.0.2Content-Length: 0

 

  • Was this article helpful?