Introduction

The catalog service manages offerings across geographies as the system of record. The catalog supports a RESTful API where users can retrieve information about existing offerings and create, manage, and delete their offerings. Start with the base URL and use the endpoints to retrieve metadata about services in the catalog and manage service visibility. Depending on the kind of object, the metadata can include information about pricing, provisioning, regions, and more.

API endpoint

https://resource-catalog.bluemix.net

API endpoint

https://resource-catalog.bluemix.net

API endpoint

https://resource-catalog.bluemix.net

API endpoint

https://resource-catalog.bluemix.net

Error handling

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

Returns parent catalog entries

Includes key information, such as ID, name, kind, CRN, tags, and provider. This endpoint is ETag enabled.

GET /
Request

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

  • A GET call by default returns a basic set of properties. To include other properties, you must add this parameter. A wildcard (*) includes all properties for an object, for example GET /?include=*. To include specific metadata fields, separate each field with a colon (:), for example GET /?include=metadata.ui:metadata.pricing.

  • Searches the catalog entries for keywords. Add filters to refine your search. A query filter, for example, q=kind:iaas service_name rc:true, filters entries of kind iaas with metadata.service.rc_compatible set to true and have a service name is in their name, display name, or description. Valid tags are kind:, tag:, rc:[true|false], iam:[true|false], active:[true|false], geo:, and price:

  • The field on which the output is sorted. Sorts by default by name property. Available fields are name, displayname (overview_ui.display_name), kind, provider (provider.name), sbsindex (metadata.ui.side_by_side_index), and the time created, and updated.

  • Sets the sort order. The default is false, which is ascending.

  • Return the data strings in a specified langauge. By default, the strings returned are of the language preferred by your browser through the Accept-Langauge header, which allows an override of the header. Languages are specified in standard form, such as en-us. To include all languages use a wildcard (*).

  • Returns all available fields for all languages. Use the value ?complete=true as shortcut for ?include=&languages=.

Example requests
Response

Status Code

  • Successful search result. Your permissions determine what you can see.

Example responses

Create a catalog entry

The created object is restricted by default. You must have an administrator or editor role in the scope of the provided token. This API will return an ETag that can be used for standard ETag processing, except when depth query is used.

POST /
Request

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Object to post

Example requests
Response

Status Code

  • Successfully created a catalog entry.

  • The request was invalid. Such as invalid depth query parameter.

  • Unauthorized

  • Permission Denied: You must have an Adminstrator or editor role to create a catalog entry.

No Sample Response

This method does not specify any sample responses.

Get a specific catalog object

This endpoint returns a specific catalog object using the object's unique identifier, for example /*service_name*?complete=true. This endpoint is ETag enabled.

GET /{id}
Request

Path Parameters

  • The object's unqiue ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

  • A GET call by default returns a basic set of properties. To include other properties, you must add this parameter. A wildcard (*) includes all properties for an object, for example GET /id?include=*. To include specific metadata fields, separate each field with a colon (:), for example GET /id?include=metadata.ui:metadata.pricing.

  • Return the data strings in the specified langauge. By default the strings returned are of the language preferred by your browser through the Accept-Langauge header, which allows an override of the header. Languages are specified in standard form, such as en-us. To include all languages use a wildcard (*).

  • Returns all available fields for all languages. Use the value ?complete=true as shortcut for ?include=&languages=.

  • Return the children down to the requested depth. Use * to include the entire children tree. If there are more children than the maximum permitted an error will be returned. Be judicious with this as it can cause a large number of database accesses and can result in a large amount of data returned.

Example requests
Response

Status Code

  • A catalog entry object

  • Unauthorized

  • No Permissions

  • Object was not found.

Example responses

Update a catalog entry

Update a catalog entry. The visibility of the object cannot be modified with this endpoint. You must be an administrator or editor in the scope of the provided token. This endpoint is ETag enabled.

PUT /{id}
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

  • Reparenting object. In the body set the parent_id to a different parent. Or remove the parent_id field to reparent to the root of the catalog. If this is not set to 'true' then changing the parent_id in the body of the request will not be permitted. If this is 'true' and no change to parent_id then this is also error. This is to prevent accidental changing of parent.

Object to post

Example requests
Response

Status Code

  • Successfully updated the catalog entry.

  • There is a validation error. Use accept=application/json to see all of the validation errors.

  • Unauthorized.

  • Permission Denied: You must have an Adminstrator or editor role to update this catalog entry.

  • Object was not found.

No Sample Response

This method does not specify any sample responses.

Archive a catalog entry

Archive a catalog entry. This will archive the entry for a minimum of two weeks. While archived, it can be restored using the PUT restore API. After two weeks, it will be deleted and cannot be restored. You must have administrator role in the scope of the provided token to modify it. This endpoint is ETag enabled.

DELETE /{id}
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • Successfully archived the catalog entry, or it was already archived or did not exist.

  • Unauthorized.

  • Permission Denied: You must have an Adminstrator role to create a catalog entry.

No Sample Response

This method does not specify any sample responses.

Get child objects of a specific kind

Fetch child objects for an object with a specific id. This endpoint is ETag enabled.

GET /{id}/{kind}
Request

Path Parameters

  • The parent object ID

  • The kind of child objects to search for. A wildcard (*) includes all child objects for all kinds, for example GET /service_name/*.

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

  • A colon (:) separated list of properties to include. A GET call by defaults return a limited set of properties. To include other properties, you must add the include parameter. A wildcard (*) includes all properties

  • A query filter, for example, q=kind:iaas IBM will filter on entries of kind iaas that has IBM in their name, display name, or description.

  • The field on which to sort the output. By default by name. Available fields are name, kind, and provider.

  • The sort order. The default is false, which is ascending.

  • Return the data strings in the specified langauge. By default the strings returned are of the language preferred by your browser through the Accept-Langauge header. This allows an override of the header. Languages are specified in standard form, such as en-us. To include all languages use the wildcard (*).

  • Use the value ?complete=true as shortcut for ?include=&languages=.

Example requests
Response

Status Code

  • Get a list of child object

Example responses

Restore archived object

Restore an archived object. You must have an administrator role in the scope of the provided token.

PUT /{id}/restore
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • Successfully restored the catalog entry.

  • Unauthorized

  • Permission Denied: You must have an Adminstrator role to set visibility of a catalog entry.

  • Object was not found.

No Sample Response

This method does not specify any sample responses.

Get the visibility constraints for an object

This endpoint returns the visibility rules for this object. Overall visibility is determined by the parent objects and any further restrictions on this object. You must have an administrator role in the scope of the provided token. This endpoint is ETag enabled.

GET /{id}/visibility
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • The entry visibility object

  • Unauthorized

  • No Permissions

  • Object was not found

Example responses

Update visibility

Update an Object's Visibility. You must have an administrator role in the scope of the provided token. This endpoint is ETag enabled.

PUT /{id}/visibility
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Object to post

Example requests
Response

Status Code

  • Successfully updated the visibility of the catalog entry.

  • Unauthorized

  • Permission Denied: You must have an Adminstrator role to set visibility of a catalog entry.

  • Object was not found.

No Sample Response

This method does not specify any sample responses.

Get the pricing for an object

This endpoint returns the pricing for an object. Static pricing is defined in the catalog. Dynamic pricing is stored in Bluemix Pricing Catalog.

GET /{id}/pricing
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • The pricing for the object

  • Unauthorized

  • No Permissions

  • Pricing not available

Example responses

Get the audit logs for an object

This endpoint returns the audit logs for an object. Only administrators and editors can get logs.

GET /{id}/logs
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

  • Sets the sort order. False is descending.

    Default: false

  • Starting time for the logs. If it's descending then the entries will be equal or earlier. The default is latest. For ascending it will entries equal or later. The default is earliest. It can be either a number or a string. If a number then it is in the format of Unix timestamps. If it is a string then it is a date in the format YYYY-MM-DDTHH:MM:SSZ and the time is UTC. The T and the Z are required. For example: 2017-12-24T12:00:00Z for Noon UTC on Dec 24, 2017

  • Count of number of log entries to skip before returning logs. The default is zero.

    Default: 0

  • Count of number of entries to return. The default is fifty. The maximum value is two hundred.

    Constraints: value ≤ 200

    Default: 50

Example requests
Response

Status Code

  • The audit logs for the object

  • Unauthorized

  • No Permissions

  • Object not found or is archived

Example responses

Get artifacts

This endpoint returns a list of artifacts for an object.

GET /{object_id}/artifacts
Request

Path Parameters

  • The object's unique ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Artifacts List

Status Code

  • The artifacts for the object

  • Unauthorized

  • No Permissions

  • Artifact not found

Example responses

Get artifact

This endpoint returns the binary of an artifact.

GET /{object_id}/artifacts/{artifact_id}
Request

Path Parameters

  • The object's unique ID

  • The artifact's ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • The binary of the artifact

  • If using header 'If-None-Match' with an ETag this will be returned if the ETag matches.

  • Unauthorized

  • No Permissions

  • Artifact not found

No Sample Response

This method does not specify any sample responses.

Upload artifact

This endpoint uploads the binary for an artifact. Only administrators and editors can upload artifacts.

PUT /{object_id}/artifacts/{artifact_id}
Request

Path Parameters

  • The object's unique ID

  • The artifact's ID. The ID cannot start with the prefix '/cache/'. This is reserved and not allowed.

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • Successfully uploaded the artifact

No Sample Response

This method does not specify any sample responses.

Delete artifact

This endpoint deletes an artifact. Only administrators and editors can delete artifacts.

DELETE /{object_id}/artifacts/{artifact_id}
Request

Path Parameters

  • The object's unique ID

  • The artifact's ID

Query Parameters

  • This changes the scope of the request regardless of the authorization header. Example scopes are account and global. account=global is reqired if operating with a service ID that has a global admin policy, for example GET /?account=global.

Example requests
Response

Status Code

  • Successfully deleted the artifact

  • Unauthorized

  • No Permissions

  • Artifact not found

No Sample Response

This method does not specify any sample responses.