Skip to main content
Hitachi Vantara Knowledge

Introduction to the HCP management API

The Hitachi Content Platform (HCP) management API is a RESTful HTTP interface to a subset of the administrative functions of an HCP system. Using this API, you can manage tenants, namespaces, retention classes, content classes, and tenant-level user and group accounts (HCP tenants only).

Each entity you can manage is referred to as a resource. Each resource has properties that provide information about it.

Note
  • Most of the examples in this book use cURL and Python with PycURL, a Python interface that uses the libcurl library. cURL and PycURL are both freely available open-source software. You can download them from http://curl.haxx.se.
  • In version 7.12.1 of PycURL, the PUT method was deprecated and replaced with UPLOAD. The Python examples in this book show UPLOAD but work equally well with PUT.

What you can do with the management API

The HCP management API lets you work with tenants, namespaces, retention classes, content classes, and tenant-level user and group accounts.

For tenants, you can:

  • Modify HCP tenants
  • Retrieve information about a single tenant
  • Set default properties for namespaces created for an HCP tenant
  • Retrieve statistics about the content of the namespaces owned by a tenant
  • Generate a chargeback report for an HCP tenant

For namespaces, you can:

  • Create HCP namespaces
  • Modify namespaces
  • Delete HCP namespaces
  • Retrieve information about a single namespace
  • Retrieve a list of all the namespaces owned by a tenant
  • Retrieve statistics about the content of a namespace
  • Generate a chargeback report for an HCP namespace
  • Reset the indexing checkpoint for a namespace

For retention classes, you can:

  • Create, modify, and delete retention classes for a namespace
  • Retrieve information about a single retention class
  • Retrieve a list of all the retention classes defined for a namespace

For content classes, you can:

  • Create, modify, and delete content classes for a tenant
  • Retrieve information about a single content class
  • Retrieve a list of all the content classes defined for a tenant

For HCP tenant-level user accounts, you can:

  • Create, modify, and delete user accounts
  • Retrieve information about a single user account
  • Retrieve a list of all the user accounts defined for a tenant

For HCP tenant-level group accounts, you can:

  • Create, modify, and delete group accounts
  • Retrieve information about a single group account
  • Retrieve a list of all the group accounts defined for a tenant
  • Create a new group account with the security role or give the security role to an existing group account

Who can use the management API

To use the HCP management API, you need either a system-level or tenant-level user account that’s defined in HCP. If HCP is configured to support Windows® Active Directory® (AD), clients can also use recognized AD user accounts to access HCP through the management API. A recognized AD user account is an AD user account for a user that belongs to one or more AD groups for which corresponding group accounts are defined in HCP.

What you can do with the API depends on:

  • The level of account you’re using
  • The roles associated with the account (or applicable group accounts)
  • For tenant-level accounts, whether the account (or applicable group accounts) has the allow namespace management property

The permissions granted by each role have the same effect with the management API as they do in the Tenant Management Console . For example, with an HCP tenant-level user account that includes the administrator role, you can create, modify, and delete namespaces. With a tenant-level user account that includes only the monitor role, you can only retrieve information about these entities.

An HCP tenant can grant system-level users administrative access to itself. This enables users with system-level user accounts to perform the activities allowed by the tenant-level roles that correspond to their system-level roles.

If you have only the allow namespace management property and no roles, the activities you can perform with the HCP management API are limited to creating namespaces, listing and deleting namespaces you own, and viewing and modifying the versioning status of namespaces you own.

For you to use the management API with a system-level user account, the API must be enabled at the system level. For you to use the management API with a tenant-level user account, the API must be enabled at both the system and tenant levels.

Resources and properties

Each entity that you can manage independently in the HCP management API is called a resource. Examples of resources are tenants and namespaces.

Resources have properties. The values of these properties describe the resource. For example, tenant properties include the tenant name, description, and whether system-level users can manage the tenant.

Some properties are treated as resources in their own right. For example, the Tenant Management Console configuration is a property of a tenant, but it is treated as a resource.

To identify a resource, you use a URL. For example, this URL identifies the tenant resource named Finance in the HCP system named hcp.example.com:

https://finance.hcp.example.com:9090/mapi/tenants/finance

You also use URLs to identify lists of resources. For example, this URL identifies the list of namespaces owned by the Finance tenant:

https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces

Each URL that identifies a resource or list of resources has a data type. For a list of resources, the data type is list. For an individual resource, the data type is a named unordered set of properties. For example, the data type for the retention class resource is retentionClass. The properties included in this data type are name, value, description, and allowDisposition.

Properties also have data types. The data type of a property can be string, integer, long, Boolean, or list, or it can be another named unordered set of properties. For example, the name property for a tenant resource has a data type of string. The ipSettings property for a Tenant Management Console configuration resource has a data type of ipSettings.

Supported methods

The HCP management API supports the HTTP methods listed in the list below.

  • PUT

    Creates a resource.

    When creating a resource, you need to supply values for all properties that do not have default values. If properties with default values are omitted from the request body, those values are applied to the resource.

  • GET

    Retrieves information about an individual resource or retrieves a list of resources of a given type.

  • HEAD

    Performs a GET but does not return the response body. You can use a HEAD request to check whether a particular resource exists.

  • POST

    Modifies a resource.

    When modifying a resource, you need to supply values only for the properties whose values you want to change. If properties are omitted from the request body, they remain unchanged.

  • DELETE

    Deletes a resource.

  • OPTIONS

    Describes the methods supported by a given resource.

Each request you submit to the management API can work on only one resource. So, for example, you cannot use a single PUT request to create two tenants.

Input and output formats

When you create or modify a resource through the HCP management API, you use XML or JSON to specify the resource properties. When you request information about resources, you can ask for the response to be returned in XML format or in JSON format. For one resource, chargebackReport, you can also ask for the response to be returned in CSV format.

The response to an OPTIONS request is always returned as Web Application Description Language (WADL). WADL is an XML-based description language for HTTP-based web applications.

All responses returned through the management API are UTF-8 encoded. The request bodies you create for input to the API must also be UTF-8 encoded.

HTTP Content-Type and Accept headers

With a PUT or POST request, you use the HTTP Content-Type request header to specify the format of the request body. This header is required if the request includes a request body.

With a GET request, you can use the HTTP Accept request header to specify the format for the response body. If you omit this header, the API returns the response body in XML format.

In a Content-Type or Accept header, you specify the input or output format as an Internet media type:

  • For XML, the Internet media type is application/xml.
  • For JSON, the Internet media type is application/json.
  • For JSON with callback, the Internet media type is application/javascript.
  • For CSV, the Internet media type is text/csv.

You don’t need to specify an Internet media type in an OPTIONS request. If you do specify one, it is ignored.

With cURL, you use the -H option to specify an HTTP header. So, for example, to specify that a request body uses XML, you include this in the curl command:

-H "Content-Type: application/xml"

In Python with PycURL, you do this with the HTTPHEADER option. For example:

curl.setopt(pycurl.HTTPHEADER, ["Content-Type: application/xml"])

HTTP headers and Internet media types are not case sensitive.

XML

In an XML request or response body:

  • Property names are element names. Property values are element values. For example, the element that corresponds to the softQuota property with a value of 85 is:
    <softQuota>85</softQuota>
  • The name of the root element for a request that involves a single resource is the data type of that resource. For example, for this URL, which identifies a single namespace named Accounts-Receivable, the root element is namespace:
    https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/Accounts-Receivable
  • The name of the root element for a request for a list of resources is the term used to identify those resources in the URL. For example, for this URL, the root element is namespaces:
    https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces
  • In a list of resources, each resource is the value of an element whose name is the name of the property used to identify the resource. For example, the response body for a request for the namespaces owned by the Finance tenant might include this:
    <namespaces>
        <name>Accounts-Payable</name>
        <name>Accounts-Receivable</name>
    </namespaces>

Here’s a request for complete information about the Accounts-Receivable namespace to be returned in XML format:

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

Here’s the XML response body you get when you make the request using a user account that includes the administrator role:

<namespace>
    <aclsUsage>ENFORCED</aclsUsage>
    <authUsersAlwaysGrantedAllPermissions>true
    </authUsersAlwaysGrantedAllPermissions>
    <allowPermissionAndOwnershipChanges>true
    </allowPermissionAndOwnershipChanges>
    <appendEnabled>false</appendEnabled>
    <atimeSynchronizationEnabled>false</atimeSynchronizationEnabled>
    <authMinimumPermissions>
        <permission>BROWSE</permission>
        <permission>READ</permission>
        <permission>WRITE</permission>
    </authMinimumPermissions>
    <creationTime>2017-02-09T15:42:36-0500</creationTime>
    <customMetadataIndexingEnabled>true</customMetadataIndexingEnabled>
    <customMetadataValidationEnabled>true</customMetadataValidationEnabled>
    <description>Created for the Finance department at Example Company by Lee
        Green on 2/9/2017.</description>
    <dpl>Dynamic</dpl>
    <enterpriseMode>true</enterpriseMode>
    <allowErasureCoding>true</allowErasureCoding>
    <fullyQualifiedName>Accounts-Receivable.Finance.hcp.example.com
    </fullyQualifiedName>
    <hardQuota>50 GB</hardQuota>
    <hashScheme>SHA-256</hashScheme>
    <indexingDefault>true</indexingDefault>
    <indexingEnabled>true</indexingEnabled>
    <isDplDynamic>true</isDplDynamic>
    <mqeIndexingTimestamp>2017-02-26T18:11:13-0400</mqeIndexingTimestamp>
    <multipartUploadAutoAbortDays>30</multipartUploadAutoAbortDays>
    <name>Accounts-Receivable</name>
    <optimizedFor>CLOUD</optimizedFor>
    <owner>pblack</owner>
    <ownerType>LOCAL</ownerType>
    <readFromReplica>true</readFromReplica>
    <replicationEnabled>true</replicationEnabled>
    <replicationTimestamp>2017-02-27T06:45:52-0500</replicationTimestamp>
    <searchEnabled>true</searchEnabled>
    <servicePlan>Short-Term-Activity</servicePlan>
    <serviceRemoteSystemRequests>true</serviceRemoteSystemRequests>
    <softQuota>75</softQuota>
    <tags>
        <tag>Billing</tag>
        <tag>lgreen</tag>
    </tags>
    <id>0e774b8d-8936-4df4-a352-b68766b5c287</id>
    <authAndAnonymousMinimumPermissions>
        <permission>BROWSE</permission>
        <permission>READ</permission>
    </authAndAnonymousMinimumPermissions>
</namespace>
JSON

In a JSON request or response body:

  • Properties are name/value pairs. For example, the name/value pair that corresponds to the softQuota property with a value of 85 is:
    "softQuota":"85"
  • A list of resources is represented by a name/value pair, where the name is the name of the property used to identify each resource and the value is a comma-separated list of the resource identifiers. For example, the response body for a request to list the the namespaces owned by the Finance tenant might look like this:
    {
        "name" : [ "Accounts-Payable", "Accounts-Receivable ]
    }

Here’s a request for complete information about the Accounts-Receivable namespace to be returned in JSON format:

curl -k -i -H "Accept: application/json"
    -H "Authorization: bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
        accounts-receivable?verbose=true&prettyprint"

Here’s the JSON response body you get when you make the request using a user account that includes the administrator role:

{
    "aclsUsage" : "ENFORCED",
    "authUsersAlwaysGrantedAllPermissions" : :true,
    "allowPermissionAndOwnershipChanges" : true,
    "appendEnabled" : false,
    "atimeSynchronizationEnabled" : false,
    "authMinimumPermissions" : {
        "permission" : [ "BROWSE", "READ", "WRITE" ]
    },
    "creationTime" : "2017-02-09T15:42:36-0500",
    "customMetadataIndexingEnabled" : true,
    "customMetadataValidationEnabled" : true,
    "description" : "Created for the Finance department at Example Company by Lee
        Green on 2/9/2017.",
    "dpl" : "Dynamic",
    "enterpriseMode" : true,
    "allowErasureCoding" : true,
    "fullyQualifiedName" : "Accounts-Receivable.Finance.hcp.example.com",
    "hardQuota" : "50 GB",
    "hashScheme" : "SHA-256",
    "indexingDefault" : true,
    "indexingEnabled" : true,
    "isDplDynamic" : true,
    "mqeIndexingTimestamp" : "2017-02-26T18:11:13-0400",
    "multipartUploadAutoAbortDays" : 30,
    "name" : "Accounts-Receivable",
    "optimizedFor" : "CLOUD",
    "owner" : "pblack",
    "ownerType" : "LOCAL",
    "readFromReplica" : true,
    "replicationEnabled" : true,
    "replicationTimestamp" : "2017-02-27T06:45:52-0500",
    "searchEnabled" : true,
    "servicePlan" : "Short-Term-Activity",
    "serviceRemoteSystemRequests" : true,
    "softQuota" : 75,
    "tags" :
        "tag" : [ "Billing", "lgreen" ]
    },
    "id" : "0e774b8d-8936-4df4-a352-b68766b5c287",
    "authAndAnonymousMinimumPermissions" : {
        "permission" : [ "BROWSE", "READ" ]
    }
}
CSV

In a CSV response body (only for a GET of a chargebackReport resource), the name of each reported property for the resource is a field in the first line. Property values are fields in the subsequent lines.

Here’s a request for the chargebackReport resource for the Accounts-Receivable namespace to be returned in CSV format:

curl -k -i -H "Accept: text/csv"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/namespaces/
         accounts-receivable/chargebackReport?start=2017-02-18T13:00:00-0500
         &end=2017-02-18T13:59:59-0500&granularity=hour"

Here’s the CSV response body:

ystemName,tenantName,namespaceName,startTime,endTime,objectCount,
    ingestedVolume,storageCapacityUsed,bytesIn,bytesOut,reads,writes,deletes,
    multipartObjects,multipartObjectParts,multipartObjectBytes,multipartUploads,
    multipartUploadParts,multipartUploadBytes,deleted,valid
hcp.example.com,Finance,Accounts-Receivable,2017-02-18T13:00:00-0500,1240,
    2017-02-18T13:59:59-0500,6,134243721,134270976,134243721,87561,1,11,0,2,
    7,93213889,0,0,0,false,true
WADL

The response body for an OPTIONS request is always returned as WADL. The HTTP response headers include Allow, which lists the supported methods for the resource.

Here’s a request for the methods you can use with the user accounts resource:

curl -k -iX OPTIONS
    -H "Authorization: bGdyZWVu:35dc4c4aa08fe0deab7e292e00eb8e97"
    "https://admin.hcp.example.com:9090/mapi/tenants/finance/userAccounts
         ?prettyprint"

Here are the response headers:

HTTP/1.1 200 OK
Content-Type: application/vnd.sun.wadl+xml
Allow: OPTIONS,HEAD,POST,GET,PUT
X-HCP-SoftwareVersion: 6.0.1.64
Content-Length: 3575

Here’s the WADL response body:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
    <doc xmlns:jersey="http://jersey.dev.java.net/"
        jersey:generatedBy="Jersey: 1.1.5 01/20/2010 04:04 PM"/>
    <resources base="https://admin.hcp.example.com:9090/mapi/">
        <resource path="tenants/finance/userAccounts">
            <method name="PUT" id="createUserAccount">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="password"/>
                    <representation mediaType="application/xml"/>
                    <representation mediaType="application/json"/>
                </request>
                <response>
                    <representation mediaType="*/*"/>
                </response>
            </method>
            <method name="HEAD" id="getUserAccountsHead">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="offset"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="count"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="filterType"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="filterString"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="sortType"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="sortOrder"/>
                </request>
                <response>
                    <representation mediaType="application/xml"/>
                    <representation mediaType="application/json"/>
                    <representation mediaType="application/javascript"/>
                </response>
            </method>
            <method name="GET" id="getUserAccounts">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="offset"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="count"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="filterType"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="filterString"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="sortType"/>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="sortOrder"/>
                </request>
                <response>
                    <representation mediaType="application/xml"/>
                    <representation mediaType="application/json"/>
                    <representation mediaType="application/javascript"/>
                </response>
            </method>
            <method name="POST" id="resetPasswords">
                <request>
                    <param xmlns:xs="http://www.w3.org/2001/XMLSchema"
                        type="xs:string" style="query" name="resetPasswords"/>
                </request>
                <response>
                    <representation mediaType="application/xml"/>
                    <representation mediaType="application/json"/>
                </response>
            </method>
        </resource>
    </resources>
</application>

Query parameters

Some HCP management API requests take query parameters. Query parameters are appended to a resource URL following a question mark (?). Multiple parameters are joined by ampersands (&).

The following considerations apply to query parameters:

  • If you specify an invalid value for a query parameter that requires a Boolean value (true or false), HCP interprets the value as false.
  • If you specify an invalid value for any other required or optional query parameter, HCP returns a status code of 400 (Bad Request).
  • If you omit a required query parameter, HCP returns a status code of 400 (Bad Request).
  • If you specify a query parameter that’s not valid for the request, HCP ignores it.

Query parameter names are case sensitive.

verbose

The verbose query parameter tells HCP how much information to return in response to a GET request for information about a resource. Valid values for this parameter are true and false.

In most cases, with verbose=false, a request for information about a resource returns only the properties whose values you can modify. For example, you cannot change the type of authentication for a user account. So, when you use GET with verbose=false to retrieve information about a user account, the localAuthentication property is omitted from the response body.

To retrieve all the properties for a resource, you need to append verbose=true to the resource URL. If you omit the verbose parameter, HCP uses the default value false.

prettyprint

The prettyprint query parameter causes the XML or JSON returned in response to a GET request to be formatted for readability. For example, with the prettyprint parameter, the returned XML for a list of namespaces looks like this:

<namespaces>
    <name>Accounts-Payable</name>
    <name>Accounts-Receivable</name>
</namespaces>

Without the prettyprint parameter, the returned XML looks like this:

<?xml version="1.0" encoding="UTF-8"?><namespaces><name>Accounts-Payable</name><name>Accounts-Receivable</name></namespaces>

The prettyprint parameter increases the time it takes to process a request. Therefore, you should use it only for testing purposes and not in production applications.

Request-specific query parameters

Some requests take query parameters that provide additional information to HCP about the operation you want to perform or that request a particular operation.

When the only action you’re requesting in a POST request for a resource other than a replication resource is specified by a query parameter, you need to provide an empty request body. With cURL, you specify this body as the argument for the -d option in the request:

With a content type of XML, the argument is an empty root element for the resource being modified, enclosed in double quotation marks, like this:

-d "<root-element/>"

For example, here’s a request to change only the password for the user account with the username mwhite:

curl -k -i -d "<userAccount/>" -H "Content-Type: application/xml"
    -H "Authorization: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6"
    "https://finance.hcp.example.com:9090/mapi/tenants/finance/
         userAccounts/mwhite?password=p4ssw0rd"

With a content type of JSON, the argument is an empty pair of curly braces enclosed in double quotation marks, like this:

-d "{}"

HCP product-specific response headers

For an HCP management API request, the HTTP response headers always include the HCP-specific X-HCP-SoftwareVersion header. The value of this header is the version number of the currently installed HCP software; for example:

X-HCP-SoftwareVersion: 9.0.0.2

If a management API request results in an error and additional information about the error is available, the HTTP response headers include the HCP-specific X-HCP-ErrorMessage header; for example:

X-HCP-ErrorMessage: 'password' parameter is required.

Security-related response headers

For an HCP management API request, the HTTP response headers always include headers that address browser security concerns. These headers have fixed values. The table below describes these headers.

HeaderValueDescription
Cache-Controlno-cache,no-store,must- revalidateSpecifies directives that must be obeyed by all caching mechanisms along the request/response chain
Content-Security- Policydefault-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe- inline'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; frame-ancestors 'self';Restricts the content that the browser can load to the sources specified by the header value
ExpiresThu, 01 Jan 1970 00:00:00 GMTCauses the response to become stale immediately after it is sent
Pragmano-cachePrevents the response from being used for subsequent requests for the same resource without the browser first checking whether the resource has changed
X-Content-Type- OptionsnosniffPrevents the browser from examining the returned content to determine the content MIME type
X-DNS-Prefetch- ControloffPrevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested
X-Download- OptionsnoopenPrevents the browser from opening resources that are downloaded through links in the returned content
X-Frame-OptionsSAMEORIGINPrevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system
X-XSS-Protection1; mode=blockStops the browser from loading the returned content if the browser detects reflected cross-site scripting (XSS) in the response
NoteThe Cache-Control and Expires headers are not returned with error responses.

Enabling the management API in the Consoles

  1. Log into the System Management Console or Tenant Management Console using a user account with the security role.

  2. In the top-level menu of either Console, select Security MAPI.

  3. In the Management API Setting section on the Management API page, select Enable the HCP management API.

  4. Click Update Settings.

 

  • Was this article helpful?