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. For more information, see the docs.

API endpoint

https://globalcatalog.cloud.ibm.com

The code examples on this tab use the client library that is provided for Node.js.

Installation

npm i ibm-platform-services

GitHub

API endpoint

https://globalcatalog.cloud.ibm.com

Creating an instance of the Global Catalog service using the Node.js SDK is shown below.

Authentication can be specified via environment variables.

export GLOBAL_CATALOG_AUTH_TYPE=iam
export GLOBAL_CATALOG_APIKEY={apikey}
const GlobalCatalogV1 = require('ibm-platform-services/global-catalog/v1');
service = GlobalCatalogV1.newInstance();

The code examples on this tab use the client library that is provided for Python.

Installation

To install, use pip or easy_install:

pip install --upgrade "platform-services>=0.4.0"

or

easy_install --upgrade "platform-services>=0.4.0"

GitHub

API endpoint

https://globalcatalog.cloud.ibm.com

Creating an instance of the Global Catalog service using the Node.js SDK is shown below.

Authentication can be specified via environment variables.

export GLOBAL_CATALOG_AUTH_TYPE=iam
export GLOBAL_CATALOG_APIKEY={apikey}
from ibm_platform_services.global_catalog_v1 import *
service = GlobalCatalogV1.new_instance()

There are a few different ways to download and install the Platform Services Go SDK project for use by your Go application:

  1. Go get command

Use this command to download and install the Platform Services Go SDK project to allow your Go application to use it:

go get -u github.ibm.com/ibmcloud/platform-services-go-sdk
  1. Go modules

If your application is using Go modules, you can add a suitable import to your Go application, like this:

import (
    "github.ibm.com/ibmcloud/platform-services-go-sdk/globalcatalogv1"
)

Next, run go mod tidy to download and install the new dependency and update your Go application's go.mod file.

  1. Dep dependency manager

If your application is using the dep dependency management tool, you can add a dependency to your Gopkg.toml file. Here is an example:

[[constraint]]
  name = "github.ibm.com/ibmcloud/platform-services-go-sdk/globalcatalogv1"
  version = "0.2.0"

then run

dep ensure

GitHub

API endpoint

https://globalcatalog.cloud.ibm.com

Creating an instance of the Global Catalog service using the Go SDK is shown below.

Authentication can be specified via environment variables.

export GLOBAL_CATALOG_AUTH_TYPE=iam
export GLOBAL_CATALOG_APIKEY={apikey}
import (
    "github.com/IBM/go-sdk-core/v3/core"
    "github.com/IBM/platform-services-go-sdk/globalcatalogv1"
)
service, _ := globalcatalogv1.NewGlobalCatalogV1UsingExternalConfig(
    &globalcatalogv1.GlobalCatalogV1Options{},
)

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>platform-services</artifactId>
    <version>0.3.0</version>
</dependency>

Gradle

'com.ibm.cloud:platform-services:0.3.0'

GitHub

API endpoint

https://globalcatalog.cloud.ibm.com

Creating an instance of the Global Catalog service using the Go SDK is shown below.

Authentication can be specified via environment variables.

export GLOBAL_CATALOG_AUTH_TYPE=iam
export GLOBAL_CATALOG_APIKEY={apikey}
import com.ibm.cloud.platform_services.global_catalog.v1.*;
import com.ibm.cloud.sdk.core.http.Response;
GlobalCatalog service = GlobalCatalog.newInstance();

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.

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

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

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

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

GET /
(globalCatalog *GlobalCatalogV1) ListCatalogEntries(listCatalogEntriesOptions *ListCatalogEntriesOptions) (result *EntrySearchResult, response *core.DetailedResponse, err error)
ServiceCall<EntrySearchResult> listCatalogEntries(ListCatalogEntriesOptions listCatalogEntriesOptions)
listCatalogEntries(params, [callback()])
list_catalog_entries(self, account=None, include=None, q=None, sort_by=None, descending=None, languages=None, complete=None, **kwargs)

Request

Instantiate the ListCatalogEntriesOptions struct and set the fields to provide parameter values for the ListCatalogEntries method.

Use the ListCatalogEntriesOptions.Builder to create a ListCatalogEntriesOptions object that contains the parameter values for the listCatalogEntries method.

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=.

The ListCatalogEntries options.

The listCatalogEntries options.

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=.

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=.

  • curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1?account=string&include=string&q=string&sort-by=string&descending=string&languages=string&complete=string' --header 'accept: application/json'
  • Response<EntrySearchResult> response = service.listCatalogEntries().execute();
    System.out.println(response.getResult());
  • response = await service.listCatalogEntries();
    console.log(response);
  • response = service.list_catalog_entries()
    print(response)
  • listOptions := service.NewListCatalogEntriesOptions()
    _, response, _ := service.ListCatalogEntries(listOptions)

Response

A paginated search result containing catalog entries.

A paginated search result containing catalog entries.

A paginated search result containing catalog entries.

A paginated search result containing catalog entries.

A paginated search result containing catalog entries.

Status Code

  • Successful search result containing a paginated list of resources that match the search criteria. Your permissions determine what you can see.

Example responses
  • {
      "page": "STRING",
      "resources": "ARRAY",
      "results_per_page": "STRING",
      "total_results": "STRING"
    }
  • {
      "page": "STRING",
      "resources": "ARRAY",
      "results_per_page": "STRING",
      "total_results": "STRING"
    }

Create a catalog entry

The created catalog entry 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.

The created catalog entry 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.

The created catalog entry 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.

The created catalog entry 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.

The created catalog entry 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 /
(globalCatalog *GlobalCatalogV1) CreateCatalogEntry(createCatalogEntryOptions *CreateCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)
ServiceCall<CatalogEntry> createCatalogEntry(CreateCatalogEntryOptions createCatalogEntryOptions)
createCatalogEntry(params, [callback()])
create_catalog_entry(self, name, kind, overview_ui, images, disabled, tags, provider, id, parent_id=None, group=None, active=None, metadata=None, account=None, **kwargs)

Request

Instantiate the CreateCatalogEntryOptions struct and set the fields to provide parameter values for the CreateCatalogEntry method.

Use the CreateCatalogEntryOptions.Builder to create a CreateCatalogEntryOptions object that contains the parameter values for the createCatalogEntry method.

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.

The catalog entry to be created.

The CreateCatalogEntry options.

The createCatalogEntry options.

parameters

  • Programmatic name for this catalog entry, which must be formatted like a CRN segment. See the display name in OverviewUI for a user-readable name.

  • The type of catalog entry, service, template, dashboard, which determines the type and shape of the object.

    Allowable values: [service,template,dashboard]

  • Overview is nested in the top level. The key value pair is [_language_]overview_ui.

  • Image annotation for this catalog entry. The image is a URL.

  • Boolean value that determines the global visibility for the catalog entry, and its children. If it is not enabled, all plans are disabled.

  • A list of tags. For example, IBM, 3rd Party, Beta, GA, and Single Tenant.

  • Information related to the provider associated with a catalog entry.

  • Catalog entry's unique ID. It's the same across all catalog instances.

  • The ID of the parent catalog entry if it exists.

  • Boolean value that determines whether the catalog entry is a group.

  • Boolean value that describes whether the service is active.

  • Model used to describe metadata object that can be set.

  • 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.

parameters

  • Programmatic name for this catalog entry, which must be formatted like a CRN segment. See the display name in OverviewUI for a user-readable name.

  • The type of catalog entry, service, template, dashboard, which determines the type and shape of the object.

    Allowable values: [service,template,dashboard]

  • Overview is nested in the top level. The key value pair is [_language_]overview_ui.

  • Image annotation for this catalog entry. The image is a URL.

  • Boolean value that determines the global visibility for the catalog entry, and its children. If it is not enabled, all plans are disabled.

  • A list of tags. For example, IBM, 3rd Party, Beta, GA, and Single Tenant.

  • Information related to the provider associated with a catalog entry.

  • Catalog entry's unique ID. It's the same across all catalog instances.

  • The ID of the parent catalog entry if it exists.

  • Boolean value that determines whether the catalog entry is a group.

  • Boolean value that describes whether the service is active.

  • Model used to describe metadata object that can be set.

  • 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.

  • curl --request POST --url 'https://globalcatalog.cloud.ibm.com/api/v1?account=string' --header 'accept: application/json'
    --data '{"active":true,"catalog_crn":"string","children":[null],"children_url":"string","created":"string","disabled":true,"geo_tags":[null],"group":true,"id":"string","images":{"description":"Image annotation for this catalog entry. The image is a URL","properties":{"feature_image":"string","image":"string","medium_image":"string","small_image":"string"},"required":["image"],"type":"object"},"kind":"string","metadata":{"additionalProperties":false,"description":"Metadata is not returned by default, and includes specific data depending on the object **kind**","properties":{"alias":{"properties":{"plan_id":"string","type":"string"},"type":"object"},"callbacks":{"properties":{"broker_proxy_url":"string","broker_utl":"string","dashboard_data_url":"string","dashboard_detail_tab_ext_url":"string","dashboard_detail_tab_url":"string","dashboard_url":"string","service_monitor_api":"string","service_monitor_app":"string","service_production_url":"string","service_staging_url":"string"},"type":"object"},"compliance":[null],"deployment":{"properties":{"broker":{"properties":{"guid":"string","name":"string","password":{"properties":{"iv":"string","key":"string","text":"string"},"type":"object"}},"type":"object"},"location":"string","location_url":"string","supports_rc_migration":true,"target_crn":"string"},"type":"object"},"origin_name":"string","other":{"description":"Additional information","type":"object"},"plan":{"properties":{"allow_internal_users":true,"async_provisioning_supported":true,"async_unprovisioning_supported":true,"bindable":true,"cf_guid":"string","reservable":true,"service_check_enabled":true,"single_scope_instance":"string","test_check_interval":0},"type":"object"},"pricing":{"properties":{"metrics":[{"amounts":[{"country":"string","currency":"string","prices":[{"Price":0,"quantity_tier":0}]}],"charge_unit_display_name":"string","charge_unit_name":"string","charge_unit_quantity":"string","metric_id":"string","resource_display_name":"string","tier_model":"string","usage_cap_qty":0}],"origin":"string","starting_price":{"properties":{"amount":[{"country":"string","currency":"string","prices":[{"Price":0,"quantity_tier":0}]}],"deployment_id":"string","plan_id":"string"},"type":"object"},"type":"string"},"type":"object"},"rc_compatible":true,"service":{"properties":{"async_provisioning_supported":true,"async_unprovisioning_supported":true,"bindable":true,"cf_guid":"string","iam_compatible":true,"plan_updateable":true,"provisionable":true,"requires":[null],"service_check_enabled":true,"service_key_supported":true,"state":"string","test_check_interval":0,"type":"string","unique_api_key":true},"type":"object"},"sla":{"properties":{"dr":{"properties":{"description":"string","dr":true},"type":"object"},"provisioning":"string","responsiveness":"string","tenancy":"string","terms":"string"},"type":"object"},"template":{"properties":{"buildpack":"string","cf_runtime_id":"string","default_memory":0,"environment_variables":{"description":"Environment variables for the template","properties":{"_key_":"string"},"type":"object"},"executable_file":"string","runtime_catalog_id":"string","services":[null],"source":{"description":"Location of your applications source files","properties":{"path":"string","type":"string","url":"string"},"type":"object"},"start_cmd":"string","template_id":"string"},"type":"object"},"ui":{"properties":{"accessible_during_provision":true,"embeddable_dashboard":"string","embeddable_dashboard_full_width":true,"end_of_service_time":"string","navigation_order":[null],"not_creatable":true,"primary_offering_id":"string","reservable":true,"side_by_side_index":0,"strings":{"description":"Language specific translation of translation properties, like label and description","properties":{"_language_":{"properties":{"bullets":[{"description":"string","icon":"string","quantity":"string","title":"string"}],"deprecation_warning":"string","instruction":"string","media":[{"URL":"string","caption":"string","source":{"properties":{"description":"string","icon":"string","quantity":"string","title":"string"},"type":"object"},"thumbnail_url":"string","type":"string"}],"not_creatable__robot_msg":"string","not_creatable_msg":"string","popup_warning_message":"string"},"type":"object"}},"type":"object"},"urls":{"description":"UI based URLs","properties":{"api_url":"string","catalog_details_url":"string","create_url":"string","custom_create_page_url":"string","deprecation_doc_url":"string","doc_url":"string","instructions_url":"string","sdk_download_url":"string","terms_url":"string"},"type":"object"}},"type":"object"},"version":"string"},"type":"object"},"name":"string","overview_ui":{"description":"Overview is nested in the top level. The key value pair is `[_language_]overview_ui`.","properties":{"_language_":{"description":"Overview is nested in the top level. The key value pair is `[_language_]overview_ui`.","properties":{"description":"string","display_name":"string","long_description":"string"},"required":["display_name","description","long_description"],"type":"object"}},"type":"object"},"parent_id":"string","parent_url":"string","pricing_tags":[null],"provider":{"properties":{"contact":"string","email":"string","name":"string","phone":"string","support_email":"string"},"required":["email","name"],"type":"object"},"tags":[null],"updated":"string","url":"string"}'
  • String id = "{id}";
    String name = "{name}";
    Boolean disabled = "{active}";
    String kind = "{kind}";
    List<String> tags = Arrays.asList("{tag});
    Overview overview = new Overview.Builder()
        .displayName("{displayName}")
        .longDescription("{longDescription}")
        .description("{description}")
        .build();
    OverviewUI overviewUi = new OverviewUI();
    overviewUi.put("{key}", overviewValueDefault);
    Image images = new Image.Builder()
        .image("{image}")
        .smallImage("{smallImage}")
        .mediumImage("{mediumImage}")
        .featureImage("{featureImage}")
        .build();Provider provider = new Provider.Builder().email("{email}").name("{name}").build();
    CreateCatalogEntryOptions createOptions = new CreateCatalogEntryOptions.Builder()
        .id(id)
        .name(name)
        .kind(kind)
        .disabled(disabled)
        .overviewUi(overviewUi)
        .images(images)
        .tags(tags)
        .provider(provider)
        .build();
    Response<CatalogEntry> response = service.createCatalogEntry(createOptions).execute();
    System.out.println(response.getResult());
  • createOptions = {
        'name': '{name}',
        'id': '{id}',
        'kind': '{kind}',
        'tags': ['{tag}'],
        'overviewUi': {
            '{key}': {
                'display_name': '{displayName}',
                'long_description': '{longDescription}',
                'description': '{description}'
            }
        },
        'images': {
            'image': '{image}',
            'small_image': '{smallImage}',
            'medium_image': '{mediumImage}',
            'feature_image': '{featureImage}'
        },    'provider': {
            'email': '{email}',
            'name': '{name}'
        }
    };
    response = await service.createCatalogEntry(createOptions);
    console.log(response);
  • createOptions = {
        'name': '{name}',
        'id': '{id}',
        'kind': '{kind}',
        'tags': ['{tag}'],
        'overviewUi': {
            '{key}': {
                'display_name': '{displayName}',
                'long_description': '{longDescription}',
                'description': '{description}'
            }
        },
        'images': {
            'image': '{image}',
            'small_image': '{smallImage}',
            'medium_image': '{mediumImage}',
            'feature_image': '{featureImage}'
        },
        'provider': {
            'email': '{email}',
            'name': '{name}'
        }
    }
    response = service.create_catalog_entry(id=createOptions['id'],
        name=self.createOptions['name'],
        overview_ui=self.createOptions['overview_ui'],
        kind=self.createOptions['kind'],
        images=self.createOptions['images'],
        disabled=self.createOptions['disabled'],
        tags=self.createOptions['tags'],
        provider=self.createOptions['provider'])
    print(response)
  • name := "{name}"
    kind := "{kind}"
    overviewUi  := &globalcatalogv1.OverviewUI{}
    overview, _ := service.NewOverview("{displayName}", "{longDescription}", "{description}")
    overviewUi.SetProperty("{key}", overview)
    images := &globalcatalogv1.Image{Image: &"{image}",
    	SmallImage:   &"{smallImage}",
    	MediumImage:  &"{mediumImage}",
    	FeatureImage: &"{featureImage}",
    }
    disabled := "{disabled}"
    tags := []string{"{tag}"}
    provider, _ := service.NewProvider("{email}", "{name}")
    id := "{id}"
    createOptions := service.NewCreateCatalogEntryOptions(name, kind, overviewUi, images, disabled, tags, provider, id)
    _, detailedResponse, _ := service.CreateCatalogEntry(createOptions)
    fmt.Println(response)

Response

An entry in the global catalog.

An entry in the global catalog.

An entry in the global catalog.

An entry in the global catalog.

An entry in the global catalog.

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 entry using the object's unique identifier, for example /*service_name*?complete=true. This endpoint is ETag enabled.

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

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

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

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

GET /{id}
(globalCatalog *GlobalCatalogV1) GetCatalogEntry(getCatalogEntryOptions *GetCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)
ServiceCall<CatalogEntry> getCatalogEntry(GetCatalogEntryOptions getCatalogEntryOptions)
getCatalogEntry(params, [callback()])
get_catalog_entry(self, id, account=None, include=None, languages=None, complete=None, depth=None, **kwargs)

Request