Administrative management methods
The management API includes administrative management methods.
Add license
The method license/add adds a license for the system. You must provide a valid license file for the licensed function to function. The method decrypts, validates, and stores the license file.
POST https://host_ip:9099/mapi/v1/license/add
The request body is:
{ "value": "license_file" }
Parameter | Required | Type | Description |
value | Yes | String | The file path of your HCP for cloud scale license. |
Not applicable.
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials were noit valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/license/add
JSON request:
{ "value": "hcpcs_license.plk" }
Get serial number
You can retrieve the current serial number of your HCP for cloud scale system.
POST https://host_ip:9099/mapi/v1/serial_number/get
Not applicable.
The response body is:
{ "value": "serial_number" }
Parameter |
Type |
Description |
value | String | The serial number of your HCP for cloud scale system. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/serial_number/get
JSON response:
{ "value": "SerialNumber48692" }
Get system chargeback report
The method chargeback/system/get_report lets a user with system-level permission generate a chargeback report on storage usage for any or all buckets defined in the system.
POST https://host_ip:9099/mapi/v1/chargeback/system/get_report
The request structure is:
{ "userName": "name", "startDateTime": "yyyy-mm-ddThh.mm.ssZ", "endDateTime": "yyyy-mm-ddThh.mm.ssZ", "granularity": "granularity", "bucketList": ["string"], "header": true|false, "reportedFields": [ "field" ] }
The response is a stream in comma-separated value (CSV) format.
Parameter | Required |
Type |
Description |
userName | No | String | Report bucket usage by the specified display name. Either a user name or a bucket list is required. |
startDateTime | No | Date-Time | The starting UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ . Truncated to the beginning of the specified hour. |
endDateTime | No | Date-Time | The ending UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ . Truncated to the beginning of the specified hour. The default is the current hour. |
granularity | No | Enum | The granularity of detail in the report:
|
bucketList | No | String | A list of buckets to include in the report. Either a user name or a bucket list is required. The default is all buckets in the specified scope. Limited to the number of buckets allowed per user. |
header | No | Boolean | If true , include column headers as the first line of the response. If false , omit the column headers. The default is false . |
reportedFields | No | String | A comma-separated list of available fields to include in the report:
The default is to return all fields. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
The following example returns a daily report for all buckets owned by the user Jimmy
for a specific date range in November 2020.
Request example:
POST https://10.10.24.195:9099/mapi/v1/chargeback/system/get_report
JSON request:
{ "userName": "Jimmy", "startDateTime": "2020-11-02T00:00Z", "endDateTime": "2020-11-04T00:00Z", "granularity": "DAILY", "header": true }
Response:
Bucket Capacity Report for user: Jimmy@example.org; Requested by: admin; Reporting period: 2020-11-02T00:00Z - 2020-11-04T00:00Z; Granularity: daily; System name: hcpcs.company.com YYYY-MM-DD,Bucket Owner,Bucket Name,Storage Class,Byte-Hour,GB-Month,Total Objects,Writes,Deletes,Written MB,Deleted MB 2020-11-02,Jimmy@example.org,bucket2,Standard,202970940,0,4,28,0,193,0 2020-11-02,Jimmy@example.org,bucket1,Standard,103229940,0,-11916,11927,11917,86,11 2020-11-03,Jimmy@example.org,bucket1,Standard,112383590,0,72,74,0,32,0 2020-11-04,Jimmy@example.org,bucket1,Standard,229915961,0,21,1121,0,3,0
Get system events
The method system/info retrieves the 100 most recent system events.
POST https://host_ip:9099/mapi/v1/system/info
Not applicable.
The response body is:
{ "events": [ { "severity": "INFO|WARNING|SEVERE", "subject": "event_subject", "message": "event_message", "subsystem": "event_subsystem", "timestamp": date_time }, . . . ] }
Parameter |
Type |
Description |
severity | String | The severity of the event:
|
subject | String | Summary of the event. |
message | String | Details about the event. |
subsystem | String | The event category (for example, User, Bucket, or S3 settings). |
timestamp | 64-bit integer | The date and time, in milliseconds since 00:00:00 on 1 January 1970 GMT, when the event was generated. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/system/info
JSON response:
{ "events": [ { "severity": "INFO", "subject": "User admin@company.com authenticated", "message": "User admin@company.com with Id d3c01db4-ac18-4d90-a321-899bb210baf7 authenticated successfully to the Administration App.", "subsystem": "User", "timestamp": 1559547959735 }, { "severity": "INFO", "subject": "Unexpectedly failed authentication request by user admin@company.com", "message": "An authentication request unexpectedly failed for username admin@company.com.", "subsystem": "User", "timestamp": 1559547646844 } ] }
Get user chargeback report
The method chargeback/user/get_report lets a user generate a chargeback report on storage usage for any or all buckets defined in the system that the user owns.
POST https://host_ip:9099/mapi/v1/chargeback/user/get_report
The request structure is:
{ "startDateTime": "yyyy-mm-ddThh.mm.ssZ", "endDateTime": "yyyy-mm-ddThh.mm.ssZ", "granularity": "granularity", "bucketList": ["string"], "header": true|false, "reportedFields": [ "field" ] }
The response is a stream in comma-separated value (CSV) format.
Parameter | Required |
Type |
Description |
startDateTime | No | Date-Time | The starting UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ . Truncated to the beginning of the specified hour. |
endDateTime | No | Date-Time | The ending UTC date and time for the report, in the format yyyy-mm-ddThh.mm.ssZ . Truncated to the beginning of the specified hour. The default is the current hour. |
granularity | No | Enum | The granularity of detail in the report:
|
bucketList | No | String | A list of buckets to include in the report. The default is all buckets that the user owns. Limited to the number of buckets allowed per user. |
header | No | Boolean | If true , include column headers as the first line of the response. If false , omit the column headers. The default is false . |
reportedFields | No | String | A comma-separated list of available fields to include in the report:
The default is to return all fields. |
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
The following example returns a daily report for all buckets owned by the user (Jimmy) for a specific date range in November 2020.
Request example:
POST https://10.10.24.195:9099/mapi/v1/chargeback/system/get_report
JSON request:
{ "startDateTime": "2020-11-02T00:00Z", "endDateTime": "2020-11-04T00:00Z", "granularity": "DAILY", "header": true }
Response:
Capacity Report for user: Jimmy@example.org; Reporting period: 2020-11-02T00:00Z - 2020-11-04T00:00Z; Granularity: daily; System name: hcpcs.company.com YYYY-MM-DD,Bucket Owner,Bucket Name,Storage Class,Byte-Hour,GB-Month,Total Objects,Writes,Deletes,Written MB,Deleted MB 2020-11-02,Jimmy@example.org,bucket2,Standard,202970940,0,4,28,0,193,0 2020-11-02,Jimmy@example.org,bucket1,Standard,103229940,0,-11916,11927,11917,86,11 2020-11-03,Jimmy@example.org,bucket1,Standard,112383590,0,72,74,0,32,0 2020-11-04,Jimmy@example.org,bucket1,Standard,229915961,0,21,1121,0,3,0
List licenses
You can retrieve information about the current licenses for your HCP for cloud scale system.
POST https://host_ip:9099/mapi/v1/license/list
Not applicable.
The response body is:
{ "featureName": "feature", "uploadDate": "date_time", "expirationDate": "date_time0", "valid": {true|false}, "message": "message" }
Parameter |
Type |
Description |
featureName | String | Name of the licensed feature. |
uploadDate | The date and time, in the format Ddd Mmm dd hh:mm:ss TMZ yyyy, when the license was uploaded. | |
expirationDate | The date and time, in the format Ddd Mmm dd hh:mm:ss TMZ yyyy, when the license expires. | |
valid | Boolean | If true, the license is valid. If false, the license is invalid. |
message | String | State of the license:
|
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/license/list
JSON response:
{ "featureName": "DARE", "uploadDate": "Tue Jun 16 00:00:00 GMT 2020", "expirationDate": "Sat Oct 24 10:24:54 GMT 2020", "valid": true, "message": "License is valid" }
Refresh client certificates
If your system uses the HTTPS protocol and you change an SSL certificate, you need to update the certificates on storage components.
POST https://host_ip:9099/mapi/v1/certificates/refresh
Not applicable.
Not applicable.
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials are not valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/certificates/refresh
Set serial number
The method serial_number/set sets the serial number of the HCP for cloud scale system. You must provide a valid serial number for the system to function.
POST https://host_ip:9099/mapi/v1/serial_number/set
The request body is:
{ "value": "serial_number" }
Parameter | Required | Type | Description |
value | Yes | String | The serial number of your HCP for cloud scale system. |
The response returns the same parameter as the request.
Status code |
HTTP name |
Description |
200 | OK | The request was executed successfully. |
401 | Unauthorized | Access was denied because credentials were noit valid. |
405 | Method Not Allowed | The specified HTTP method is not allowed for administrative data. Resend using POST. |
Request example:
POST https://10.10.24.195:9099/mapi/v1/serial_number/set
JSON request:
{ "value": "SerialNumber48692" }
JSON response:
{ "value": "SerialNumber48692" }