Operating and Managing

Hitachi Content
Platform v8.2

Management API

© Hitachi Vantara LLC 2020. All Rights Reserved.

Module Objectives

 When you complete this module, you should be able to:

• Explain the basic concept of Management API
• Determine who can use MAPI
• List the steps to enable MAPI
• Discuss the steps to modify a resource through the HCP management API

© Hitachi Vantara LLC 2020. All Rights Reserved.

What Is the HCP Management API?

 Tenant-level MAPI is a RESTful HTTP interface to a subset of the

administrative functions of an HCP system

 You can manage tenants, namespaces, retention classes, content

classes, and tenant-level user and group accounts

 Each entity you can manage is referred to as a resource and has

properties that provide information about it

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 Namespaces
• Create, modify, and 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 Retention classes
• 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 Content classes
• 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 Tenant-level user accounts

• 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

What You Can Do With MAPI

 Tenant-level group accounts

• 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

© Hitachi Vantara LLC 2020. All Rights Reserved.

 Active Learning Exercise: Raise Your Hands If
You Know It!
Describe some of the things the Tenant user can do with
Management API?

0 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Who Can Use the Management API?

 You need either a system-level or tenant-level user account that’s

defined in HCP

 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

1 © Hitachi Vantara LLC 2020. All Rights Reserved.

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

2 © Hitachi Vantara LLC 2020. All Rights Reserved.

 HTTP(S) Methods Supported by MAPI

 PUT Creates a 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

 POST Modifies a resource

 DELETE Deletes a resource

 OPTIONS Describes the methods supported by a given resource

3 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Input and Output Formats Supported by MAPI

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

4 © Hitachi Vantara LLC 2020. All Rights Reserved.

 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 (&)

5 © Hitachi Vantara LLC 2020. All Rights Reserved.

 HCP Product-specific 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: 8.3.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

6 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Instructions for Enabling MAPI

 To enable the HCP management API in the System and Tenant

Management Consoles:

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

2. In the top-level menu of the 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.

7 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Active Learning Exercise: Follow the Manual

To get detailed information about Management API, as well as some great

examples, refer to the HCP Tenant Management Help.

8 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Access and Authentication

 With the HCP management API, resources are represented by URLs

• Each request you make must specify one such URL
• Each request must also include the credentials for the account you’re using
to access HCP through the management API

9 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Resources

 The main types of HCP management API resources are:

• Tenants
• Namespaces
• Retention classes
• Content classes
• Tenant-level user accounts
• Tenant-level group accounts

0 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Data Types

 Many of the data types that describe HCP management API resources
and properties are named, unordered sets of properties

 When you create a resource, some properties for the applicable data
type are required and some are optional

 You need to specify a value for each required property

 If you omit an optional property, HCP supplies a default value for it

 When you modify a resource, all properties for the applicable data type
are optional

1 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Choosing an Access Method

 You can access the HCP system through the management API by
specifying either a hostname or an IP address in the resource URL
• If the system uses DNS and you specify a hostname, HCP selects the IP
address for you from the currently available nodes
• HCP uses a round-robin method to ensure that it doesn’t always select the
same address

 When you specify IP addresses, your application must take

responsibility for balancing the load among the nodes

2 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Generating Templates For Resource Creation

 When you use the HCP management API to create a resource, the best
way to ensure that the request body includes the applicable properties
is to use a template
• You can generate your own template by submitting a GET request for an
existing resource of the same type
• In the request, include the verbose=false query parameter on the resource
URL (or omit the verbose parameter to accept the default of false)

3 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Modifying Resources

 The best way to modify a resource through the HCP management API
is to:
• Submit a GET request for the resource you want to modify.
 In the request, include the verbose=false query parameter on the resource URL (or
omit the verbose parameter to accept the default of false)
 This ensures that the response body includes only the properties whose values you
can set
• In the response body from the GET request, change property values as
needed
• Submit the POST request for the resource, using the entire modified
response body as the request body

4 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Example: Creating an HCP Tenant

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

5 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Example: Creating an HCP Tenant

 Response headers
• HTTP/1.1 200 OK
• X-HCP-SoftwareVersion: 8.2.0.2
• Content-Length: 0

6 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Module Recap

 In this module we reviewed;

• HCP Management API and What You Can Do With it?
 Tenants and Namespaces
 Retention and Content Classes
 Tenant User and Group Accounts
• Who can use MAPI?
• MAPI resources and properties
• HTTP methods
• HCP product-specific headers

7 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Questions and
Discussion

8 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Module Review

1. More tasks may be accomplished through the UI than MAPI. (True or

False)

2. With MAPI you can manage Tenant-level users and groups. (True or
False)

3. What are 2 examples of resources?

4. What are 2 examples of tenant properties?

9 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Lab

REST MAPI

0 © Hitachi Vantara LLC 2020. All Rights Reserved.

 Your Next Steps **Note: This slide goes at the end of the last
content module of the course**

Follow us on
Validate yourknowledge
Validate your knowledgeandand skills
skills withwith certification
certification. social media:

Check your progress in the Learning Path.

@HitachiVantara

Review the course description for supplemental courses, or register,

enroll and view additional course offerings.

Get practical advice and insight with Hitachi Vantara white papers.

Get more knowledge, bulletins, downloads and product documentation.

Join the conversation with your peers in the Hitachi Vantara Community.

1 © Hitachi Vantara LLC 2020. All Rights Reserved.

 How did we do?
We value your feedback.

Check your email for the class survey or ask

your instructor.

2 © Hitachi Vantara LLC 2020. All Rights Reserved.