Input and output formats

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

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 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>