HPE GreenLake for Service Catalog developer guide

The details and examples in this guide will help you use the HPE GreenLake for Service Catalog APIs.

Prerequisites

Environment

The Service Catalog service is hosted at the following environment:

Hostname

The hostname for the service catalog APIs is as follows:

URI

The URIs for the service catalog APIs are as follows:

  • GET /service-catalog/v1beta1/service-managers
  • GET /service-catalog/v1beta1/service-managers/{id}
  • GET /service-catalog/v1beta1/per-region-service-managers
  • GET /service-catalog/v1beta1/per-region-service-managers/{id}

The URIs for the service provisions APIs are as follows:

  • POST /service-catalog/v1beta1/service-manager-provisions
  • GET /service-catalog/v1beta1/service-manager-provisions
  • GET /service-catalog/v1beta1/service-manager-provisions/{id}
  • DELETE /service-catalog/v1beta1/service-manager-provisions/{id}

Access and permissions

​ You need the correct role and permissions to use the HPE GreenLake Service Catalog API. A role is a group of permissions that you can specify and assign to users in your HPE GreenLake workspace. There are three basic role types distinguished by the privileges defined in the authorization service: ​

  • Administrator — has view, edit, and delete privileges in the workspace.
  • Operator — has view and edit privileges in the workspace.
  • Observer — has only view privileges in the workspace.

    ​ The Observer role with view permissions for Service Catalog (ccs.app-catalog.view) is sufficient to make Service Catalog GET API calls: ​

  • GET /service-catalog/v1beta1/service-managers
  • GET /service-catalog/v1beta1/service-managers/{id}
  • GET /service-catalog/v1beta1/per-region-service-managers
  • GET /service-catalog/v1beta1/per-region-service-managers/{id}

The Observer role with view permission for Service Provision (ccs.app-provision.view) is sufficient to make Service Provision GET API calls: ​

  • GET /service-catalog/v1beta1/service-manager-provisions
  • GET /service-catalog/v1beta1/service-manager-provisions/{id}

    ​

The Administrator / Operator role with edit permissions for Service Provision (ccs.app-provision.edit) is required to make Service Provision POST and DELETE API calls: ​

  • POST /service-catalog/v1beta1/service-manager-provisions
  • DELETE /service-catalog/v1beta1/service-manager-provisions/{id}

You can find out more in the HPE GreenLake Edge to Cloud Platform User Guide. You can: ​

  • Find a list of preconfigured roles and the permissions they have.
  • Learn how to create custom roles.
  • Discover how to assign roles to users.

Making it all Work

Generating a token

You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.

To access this HPE GreenLake Service Catalog API, proceed as follows:

  1. Connect to the HPE GreenLake edge-to-cloud platform UI workspace.
  2. Go to Manage Workspaces > API > Create Credentials .
  3. Select  HPE GreenLake platform from the Select Service Manager drop-down to create the credentials and then generate access tokens for HPE GreenLake platform service APIs. If you do not see HPE GreenLake Platform as an option when configuring API client credentials, see the Getting Started Guide for more information.

Getting an access token

With the client ID and client secret, there are two ways to fetch the access token programmatically. They are as follows:

Run the cURL command or the Python script below to get the token from the response["access_token"]:

  • Using cURL:
    Copy
    Copied
    curl -X POST https://sso.common.cloud.hpe.com/as/token.oauth2 -H

"Content-Type: application/x-www-form-urlencoded"

-d "grant_type=client_credentials&client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET"
  • Using Python:
    Copy
    Copied
    from oauthlib.oauth2 import BackendApplicationClient

from requests.auth import HTTPBasicAuth

from requests_oauthlib import OAuth2Session


client = BackendApplicationClient(YOUR_CLIENT_ID)



oauth = OAuth2Session(client=client)

auth = HTTPBasicAuth(YOUR_CLIENT_ID, YOUR_CLIENT_SECRET)



token = oauth.fetch_token(token_url='https://sso.common.cloud.hpe.com/as/token.oauth2', auth=auth)

print(token["access_token"])

This access token is used as the bearer token to authenticate the Service Catalog APIs. The token is valid for two hours.

Get service managers

Use this GET request to retrieve a list of the service managers available in your workspace.

Copy
Copied
  GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-managers

Sample API response:

Copy
Copied
{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "resourceUri": "/service-catalog/v1beta1/service-managers/3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Aruba Central",
      "description": "Manage your wired, wireless, and WAN infrastructure",
      "createdAt": "2021-04-23T07:50:30.400Z",
      "updatedAt": "2021-04-29T07:50:30.400Z",
      "generation": 1,
      "type": "/service-catalog/service-manager"
    }
  ],
  "offset": 0,
  "count": 1,
  "total": 10
}

Get service manager details

Use this GET API call to retrieve details on a particular service manager in a workspace by specifying a service manager ID. The service manager ID is 36-character alphanumeric universally unique identifier (UUID).

Copy
Copied
  GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-managers/{id}

Sample response:

Copy
Copied
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "resourceUri": "/service-catalog/v1beta1/service-managers/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Aruba Central",
  "description": "Manage your wired, wireless, and WAN infrastructure",
  "createdAt": "2021-04-23T07:50:30.400Z",
  "updatedAt": "2021-04-29T07:50:30.400Z",
  "generation": 1,
  "type": "/service-catalog/service-manager"
}

Get a list of service managers by region

Return a list of all service managers in your workspace, categorized by the regions the service managers are deployed in.

Copy
Copied
GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/per-region-service-managers

Sample response:

Copy
Copied
{
    "items": [
        {
            "id": "us-east",
            "regionName": "US East",
            "serviceManagers": [
                {
                    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "resourceUri": "/service-catalog/v1beta1/service-managers/3fa85f64-5717-4562-b3fc-2c963f66afa6",
                    "name": "Aruba Central",
                    "description": "Manage your wired, wireless, and WAN infrastructure",
                    "createdAt": "2021-04-23T07:50:30.400Z",
                    "updatedAt": "2021-04-29T07:50:30.400Z",
                    "generation": 1,
                    "type": "/service-catalog/service-manager"
                }
            ],
            "generation": 1,
            "type": "/service-catalog/service-manager"
        }
    ],
    "offset": 0,
    "count": 1,
    "total": 10
}

Filter this API by the mspSupported field using the filter query parameter, for example, filter=mspSupported eq true or filter=mspSupported eq false.

Get service managers in a specific region

Retrieve a list of all service managers deployed in a specified region. Available regions

  • ap-ausnz
  • ap-east
  • ap-northeast
  • ap-south
  • ap-southeast
  • ca-central
  • ca-east
  • cn-east
  • cn-north
  • eu-central
  • eu-north
  • eu-west
  • mea
  • sa-east
  • us-central
  • us-east
  • us-gov
  • us-west
  • att-mcd-us-west
  • att-ent-us-west
  • att-hilton-us-west
Copy
Copied
GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/per-region-service-managers/{id}

Sample response:

Copy
Copied
{
    "id": "us-west",
    "regionName": "US West",
    "serviceManagers": [
        {
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "resourceUri": "/service-catalog/v1beta1/service-managers/3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "name": "Aruba Central",
            "description": "Manage your wired, wireless, and WAN infrastructure",
            "createdAt": "2021-04-23T07:50:30.400Z",
            "updatedAt": "2021-04-29T07:50:30.400Z",
            "generation": 1,
            "type": "/service-catalog/service-manager"
        }
    ],
    "generation": 1,
    "type": "/service-catalog/service-manager"
}

Get a list of provisioned service managers

Retrieve a list of all service managers provisioned for your workspace.

Copy
Copied
GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-manager-provisions

Sample response:

Copy
Copied
{
    "items": [
        {
            "id": "2fa85f64-5717-4562-b3fc-2c963f66afa1",
            "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/2fa85f64-5717-4562-b3fc-2c963f66afa1",
            "serviceManager": {
                "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "resourceUri": "/service-catalog/v1beta1/service-manager/3fa85f64-5717-4562-b3fc-2c963f66afa6"
            },
            "region": "us-west",
            "provisionStatus": "PROVISION_INITIATED",
            "createdBy": "john@acme.com",
            "createdAt": "2021-04-23T07:50:30.400Z",
            "updatedAt": "2021-04-29T07:50:30.400Z",
            "generation": 1,
            "type": "/service-catalog/service-manager-provision"
        }
    ],
    "offset": 0,
    "count": 1,
    "total": 10
}

Filter this API by the serviceManagerId or status or by region field using the filter query parameter, for example, serviceManagerId eq '767c0c92-5ecc-4952-85d6-06d2bcaaf050' , status eq 'PROVISIONED', status eq 'UNPROVISIONED' , region eq 'us-west'.

Get a specific service manager provisioned by id for a workspace

Use this GET request to retrieve information on a provisioned service manager by supplying a service manager provisioned ID.

Copy
Copied
GET https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-manager-provisions/{id}

Sample response:

Copy
Copied
{
  "id": "2fa85f64-5717-4562-b3fc-2c963f66afa1",
  "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/2fa85f64-5717-4562-b3fc-2c963f66afa1",
  "serviceManager": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resourceUri": "/service-catalog/v1beta1/service-manager/3fa85f64-5717-4562-b3fc-2c963f66afa6"
  },
  "region": "us-west",
  "provisionStatus": "PROVISION_INITIATED",
  "createdBy": "john@acme.com",
  "createdAt": "2021-04-23T07:50:30.400Z",
  "updatedAt": "2021-04-29T07:50:30.400Z",
  "generation": 1,
  "type": "/service-catalog/service-manager-provision"
}

Provision a service manager for a workspace

Use this POST API call to provision a service manager to a chosen region in your workspace. Provisioning a service manager is an asynchronous process. Check the provisionStatus field to see the current status.

info
  • Delete any service manager provision entries that failed provisioning.
  • If a service manager provisioning already exists, a conflict is reported.
Copy
Copied
POST https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-manager-provisions

Payload:

Copy
Copied
{
    "serviceManagerId": "{id}",
    "region": "{region}"
}

Sample response:

Copy
Copied
{
    "id": "2fa85f64-5717-4562-b3fc-2c963f66afa1",
    "resourceUri": "/service-catalog/v1beta1/service-manager-provisions/2fa85f64-5717-4562-b3fc-2c963f66afa1",
    "serviceManager": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "resourceUri": "/service-catalog/v1beta1/service-manager/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    "region": "us-west",
    "createdBy": "john@acme.com",
    "generation": 1,
    "type": "/service-catalog/service-manager-provision"
}

Delete a service manager provisioned for a workspace

Use this DELETE API call to un-provision or delete a provisioned service manager. Before starting the delete operation, ensure that there are no devices associated with the workspace.

Copy
Copied
DELETE https://global.api.greenlake.hpe.com/service-catalog/v1beta1/service-manager-provisions/{id}

The DELETE API returns a 204 status code on successful deletion.

Filtering

Filters provide the ability to limit the resources that take part in the action of a REST call. When a REST call includes a filter, the action is restricted to a response that meets the filter requirements. Filters are specified by using the query parameter filter.

A filtering example

Copy
Copied
GET <URI>?filter=status eq 'PROVISIONED'

This example shows a simple filter. The resources returned by the query are limited to results when the attribute status has the value PROVISIONED. Note that within the filter, the separator is a space.

Filtering query parameters

filter = <property> <operation> <literal>

Property is the name of an attribute in the requested resource type. The property name is always to the left of the Operation.

Operation evaluated. The Service Catalog API supports the eq operation for filtering. The eq operation is used to compare the value of a property with a literal. Examples of using the eq operations:

  • eq : status eq 'UNPROVISIONED' : The status is unprovisioned.
  • eq : serviceManagerID eq '5aa0d7b7-5896-4a24-9090-71334a95db38' : Filters on a specified service manager ID.
  • eq : mspSupported eq false : MSP is not supported.

Literal the property is to be compared against. Operations compare properties against literals. For a successful matching operation, the types must match and the syntax determines the type of the literals. For example, the filter (age eq '3') would not work if age is an integer, and (age eq 3) would not work if age is a string. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent encoded equivalents.

The following examples show typed literals.

  • String : 'anything in single quotes'
    • Reserved characters in string literals must be URL encoded.
  • Integer : -100,-1,0,1,100
  • Boolean : true, false
  • Null : null.
    • Null is equal to itself and nothing else. Null is not greater or less than anything.

OData filtering reference

This filtering is a subset of OData 4.0 filtering.