Introduction

The private catalog service allows users to manage the way users in the account can interact with the public catalog, via the filtering mechanism. Users can create private catalogs, and can use these private catalogs to both manage access to the public catalog and upload their own offerings. For more information, see the catalog documentation.

API endpoint

https://cm.globalcatalog.cloud.ibm.com

API endpoint

https://cm.globalcatalog.cloud.ibm.com

API endpoint

https://cm.globalcatalog.cloud.ibm.com

API endpoint

https://cm.globalcatalog.cloud.ibm.com

Error handling

The private catalog uses standard HTTP response codes to indicate whether a method completed successfully. A 200 type response always indicates success. A 400 type response is a failure, and a 500 type response is an internal system error.

Methods

Get the account settings

Get the account level settings for the account for private catalog

GET /catalogaccount
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful response. Your permissions determine what you can see

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Set the account settings

PUT /catalogaccount
Request
Response

Status Code

  • Succesful update. Your permissions determine if can update or not.

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get the accumulated filters of the account and of the catalogs you have access to.

Get the accumulated filters of the account and of the catalogs you have access to.

GET /catalogaccount/filters
Request

Query Parameters

  • catalog id. Narrow down filters to the account and just the one catalog.

Response

The accumulated filters for an account. This will return the account filters plus a filter for each catalog the user has access to.

Status Code

  • Successful response. Your permissions determine what you can see

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get list of catalogs

List the available catalogs for a given account

GET /catalogs
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful response. Your permissions determine what you can see

No Sample Response

This method does not specify any sample responses.

Create a catalog

Create a catalog for a given account

POST /catalogs
Request
Response

Status Code

  • Successful creation

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

/catalogs/{catalogID}

GET /catalogs/{catalogID}
Request

Path Parameters

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog id

No Sample Response

This method does not specify any sample responses.

/catalogs/{catalogID}

PUT /catalogs/{catalogID}
Request

Path Parameters

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog id

No Sample Response

This method does not specify any sample responses.

/catalogs/{catalogID}

DELETE /catalogs/{catalogID}
Request

Path Parameters

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog

No Sample Response

This method does not specify any sample responses.

Get list of offerings for consumption

List the available offerings from both public and from the account that currently scoped for consumption. These copies cannot be used updating. They are not complete and only return what is visible to the caller.

GET /offerings
Request

Query Parameters

  • true - Strip down the content of what is returned. For example don't return the readme. Makes the result much smaller. Defaults to false.

  • catalog id. Narrow search down to just a particular catalog. It will apply the catalog's public filters to the public catalog offerings on the result.

  • What should be selected. Default is 'all' which will return both public and private offerings. 'public' returns only the public offerings and 'private' returns only the private offerings.

    Allowable values: [all,public,private]

  • true - include offerings which have been marked as hidden. The default is false and hidden offerings are not returned.

Response

Status Code

  • Successful response. Your permissions determine what you can see

No Sample Response

This method does not specify any sample responses.

Get list of offerings

List the available offerings in the specified catalog

GET /catalogs/{catalogID}/offerings
Request

Path Parameters

Response

Status Code

  • Successful response. Your permissions determine what you can see

No Sample Response

This method does not specify any sample responses.

Create an offering

Create an offering

POST /catalogs/{catalogID}/offerings
Request

Path Parameters

Response

Status Code

  • Successful creation

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Import new version to offering from a tgz

Import new version to offering from a tgz

POST /catalogs/{catalogID}/offerings/{offeringID}/version
Request

Path Parameters

Query Parameters

  • The semver value for this new version, if not found in the zip url package content

  • Add all possible configuration values to this version when importing

Response

Status Code

  • New version created

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Import a new offering from a tgz

Import a new offering from a tgz

POST /catalogs/{catalogID}/import/offerings
Request

Path Parameters

Query Parameters

  • Re-use the specified offeringID during import

  • Add all possible configuration items when creating this version

Response

Status Code

  • New offering created

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Reload existing version in offering from a tgz

Reload exsiting version in offering from a tgz

PUT /catalogs/{catalogID}/offerings/{offeringID}/reload
Request

Path Parameters

Query Parameters

  • The semver value for this new version

Response

Status Code

  • New version created

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get an offering

Get an offering

GET /catalogs/{catalogID}/offerings/{offeringID}
Request

Path Parameters

  • catalog's ID

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

Update an offering

Update an offering

PUT /catalogs/{catalogID}/offerings/{offeringID}
Request

Path Parameters

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

Delete an offering

Delete an offering

DELETE /catalogs/{catalogID}/offerings/{offeringID}
Request

Path Parameters

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalogg

No Sample Response

This method does not specify any sample responses.

upload an icon for the offerring

upload an icon file to be stored in GC. File is uploaded as a binary payload - not as a form

PUT /catalogs/{catalogID}/offerings/{offeringID}/icon/{fileName}
Request

Path Parameters

  • catalog's ID

  • Name of the file name that is being uploaded

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

Approve offering to be permitted to publish to IBM Public Catalog (IBMers only or Everyone)

Approve or disapprove the offering to be allowed to publish to the IBM Public Catalog in ibm (visible to IBM only) or public (visible to everyone). Can approve to only ibm, or it can be extended to public. If extended to public then ibm is automatically approved too. If disapprove public, then ibm approval will not be changed. If disapprove ibm then public will automatically be disapproved. This is because the process steps always go first through ibm and then to public. ibm cannot be skipped. Only users with Approval IAM authority can use this.

POST /catalogs/{catalogID}}/offerings/{offeringID}}/publish/{type}/{setting}
Request

Path Parameters

  • catalog's ID

  • offering's ID

  • Type of approval, ibm or public

    Allowable values: [ibm,public]

  • Approve or disapprove

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

Get the about information, in markdown, for the current version

Get the about information, in markdown, for the current version

GET /versions/{versionLocatorID}/about
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Successful response. Your permissions determine what you can see

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get the license content for the specified license ID in the specified version

Get the license content for the specified license ID in the specified version

GET /versions/{versionLocatorID}/licenses/{licenseID}
Request

Path Parameters

  • A dotted value of catalogID.versionID

  • The ID of the license, which maps to the file name in the 'licenses' directory of this verions tgz file

Response

Status Code

  • Successful response. Your permissions determine what you can see

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get get the list of container images associated with this version

The "image_manifest_url" property of the version should be pointing the a URL for the image manifest, this api reflects that content

GET /versions/{versionLocatorID}/containerImages
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Successful response. A list of images

No Sample Response

This method does not specify any sample responses.

Deprecate the specified version

Deprecate the specified version

POST /versions/{versionLocatorID}/deprecate
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted.

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Publish the specified version so it is viewable by account members

Publish the specified version so it is viewable by account members

POST /versions/{versionLocatorID}/account-publish
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted.

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Publish the specified version so that it is visible to IBMers in the public catalog

Publish the specified version so that it is visible to IBMers in the public catalog

POST /versions/{versionLocatorID}/ibm-publish
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted.

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Publish the specified version so it is visible to all users in the public catalog

Publish the specified version so it is visible to all users in the public catalog

POST /versions/{versionLocatorID}/public-publish
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted.

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Commit a working copy of the specified version

Commit a working copy of the specified version

POST /versions/{versionLocatorID}/commit
Request

Path Parameters

  • A dotted value of catalogID.versionID for either the working copy to commit or the active version with a working copy to be committed.

Response

Status Code

  • Working Copy Committed

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Create a working copy of the specified version

Create a working copy of the specified version

POST /versions/{versionLocatorID}/workingcopy
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Working Copy Created

  • Bad request

  • Unauthorized

  • No Permissions

  • Working Copy already exists

No Sample Response

This method does not specify any sample responses.

Get available updates for the specified version

Get available updates for the specified version

GET /versions/{versionLocatorID}/updates
Request

Custom Headers

  • The refresh token for the current user

Path Parameters

  • A dotted value of catalogID.versionID

Query Parameters

  • The id of the cluster where this version was installed

  • The region of the cluster where this version was installed

  • The resource group id of the cluster where this version was installed

  • The namespace of the cluster where this version was installed

Response

Status Code

  • Version Descriptors, sorted newest first

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get the Offering/Kind/Version 'branch' for the specified locator ID

Get the Offering/Kind/Version 'branch' for the specified locator ID

GET /versions/{versionLocatorID}
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Successful response. Your permissions determine what you can see

No Sample Response

This method does not specify any sample responses.

Delete a version

Delete a the specified version. If the version is an active version with a working copy, the working copy will be deleted as well.

DELETE /versions/{versionLocatorID}
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Working Copy Deleted

  • Bad request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Search for versions

Search across all versions, requires global admin permission..

GET /versions
Request

Query Parameters

  • query, for now only "q=entitlement_key:" is supported

Response

Status Code

  • Successful response with a search result of version locators, a dotted value of catalogID.versionID

No Sample Response

This method does not specify any sample responses.

List a repo's entries

List the available entries from a given repo

GET /repo/{type}/entries
Request

Path Parameters

  • The type of repo (valid repo types: helm)

Query Parameters

  • The URL for the repo's root (e.g https://kubernetes-charts-incubator.storage.googleapis.com)

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

Get contents of a repo

Get the contents of a given repo

GET /repo/{type}
Request

Path Parameters

  • The type of repo (valid repo types: helm)

Query Parameters

  • The URL for the repo's chart zip file (e.g https://registry.bluemix.net/helm/ibm-charts/charts/ibm-redis-ha-dev-1.0.0.tgz)

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

/deploy/kubernetes/clusters

GET /deploy/kubernetes/clusters
Request

Query Parameters

  • number or results to return

  • number of results to skip before returning values

  • kubernetes or openshift. Default is kubernetes.

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

/deploy/kubernetes/clusters/{clusterID}

GET /deploy/kubernetes/clusters/{clusterID}
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • ID of the cluster

Query Parameters

  • Region of the cluster

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such cluster

No Sample Response

This method does not specify any sample responses.

/deploy/kubernetes/clusters/{clusterID}/namespaces

GET /deploy/kubernetes/clusters/{clusterID}/namespaces
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • ID of the cluster

Query Parameters

  • Cluster region

  • number or results to return

  • number of results to skip before returning values

Response

Status Code

  • List of namespaces on the cluster that are visible by the current user

  • Unauthorized

  • No Permissions

  • No such cluster

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/install

POST /versions/{versionLocatorID}/install
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/preinstall

POST /versions/{versionLocatorID}/preinstall
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/preinstall

GET /versions/{versionLocatorID}/preinstall
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Query Parameters

  • Required if the version's pre-install scope is namespace

Response

Status Code

  • Preinstall status

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/validation/install

POST /versions/{versionLocatorID}/validation/install
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Request accepted

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/validation/install

Returns the install status for the specified offering version

GET /versions/{versionLocatorID}/validation/install
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/validation/overridevalues

Returns the override values that were used to validate the specified offering version

GET /versions/{versionLocatorID}/validation/overridevalues
Request

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • JSON of override values

  • Invalid request

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/workspaces

Returns the schematics workspaces for the specified offering version

GET /versions/{versionLocatorID}/workspaces
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

  • No such catalog/offering/kind/version

No Sample Response

This method does not specify any sample responses.

/versions/{versionLocatorID}/candeploy

Returns the schematics permissions for the specified user

GET /versions/{versionLocatorID}/candeploy
Request

Custom Headers

  • IAM Refresh token

Path Parameters

  • A dotted value of catalogID.versionID

Query Parameters

Response

Status Code

  • Failed requirement checks, by pre_install and install

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

/deploy/schematics/resourcegroups

Returns all active resource groups in the current account, where the current user has permission to create schematics workspaces.

GET /deploy/schematics/resourcegroups
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful Result

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get license providers

Get license providers

GET /license/license_providers
Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

Get license entitlements

Get license entitlements bound to an account

GET /license/entitlements
Request

Query Parameters

  • The account ID to query for the entitlement. Default is the account from the user's token.

  • The license product ID. If from PPA (Passport Advantage) this is the product Part number(s) which can be one or more IDs, eg. D1YGZLL,5737L09

  • The GC ID of the specific offering version.

  • The state of the license entitlement. eg. usually 'active', or if it's been deleted will show as 'removed'.

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

Create a license entitlement

Create an entitlement for a Cloud account.  This is used to give an account an entitlement to a license.

POST /license/entitlements
Request

Query Parameters

  • if not specified the token's account will be used

Response

Status Code

  • Successful creation

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get entitlements for a specific license product ID

Get an entitlements for a specific license product ID bound to an account

GET /license/entitlements/productID/{license_product_id}
Request

Path Parameters

  • The license product ID. If from PPA (Passport Advantage) this is a specific product Part number, eg. D1YGZLL

Query Parameters

  • The account ID to query for the entitlement. Default is the account from the user's token.

  • The GC ID of the specific offering version.

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.

Delete license entitlement

Delete a license entitlement that is bound to an account. Note that BSS will mark the entitlement field "state": "removed".

DELETE /license/entitlements/{entitlement_id}
Request

Path Parameters

  • The specific entitlement ID (can be obtained from one of the license entitlement queries)

Query Parameters

  • The account ID to query for the entitlement. Default is the account from the user's token.

Response

Status Code

  • Successful response.

  • Unauthorized

  • No Permissions

No Sample Response

This method does not specify any sample responses.

Get licenses

Retrieve available licenses from supported license subsystems.  This is used to get the list of available licenses that the user has

GET /license/licenses
Request

Query Parameters

  • ID of the license provider, ie. retrieved from GET license_providers

  • if not specified the token's account will be used

  • type of license, if not specified, default is ibm-ppa

  • The license product ID. If from PPA (Passport Advantage) this is the product Part number, eg. D1YGZLL

Response

Status Code

  • Successful response.

No Sample Response

This method does not specify any sample responses.