Introduction

Last updated: 2021-10-14

The global catalog serves as the system of record for managing products across geographies. From the catalog you can find various products, including options for compute, storage, networking, solutions for app deployment, security management services, traditional and open source databases, and cloud-native services.

The catalog supports a RESTful API from which you can retrieve information about existing products. Start with the base URL and use the endpoints to retrieve metadata about products and manage catalog visibility. Depending on the kind of object, the metadata can include information about pricing, regions, resource instances, and more.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>global-catalog</artifactId>
	<version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:global-catalog:{version}'

Replace {version} in these examples with the release version.

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub

https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade "ibm-platform-services"

View on GitHub

https://github.com/IBM/platform-services-python-sdk

Installing the Go SDK

Go modules (recommended): Add the following import to your code and then run go build or go mod tidy

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

Go get

go get -u github.com/IBM/platform-services-go-sdk/globalcatalogv1

View on GitHub

https://github.com/IBM/platform-services-go-sdk

Endpoint URLs

The Global Catalog API uses the following public global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests:

https://globalcatalog.cloud.ibm.com/api/v1

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

  • Private endpoint URL for VPC infrastructure: https://private.globalcatalog.cloud.ibm.com

  • Private endpoint URLs for classic infrastructure:

    • Dallas: https://private.us-south.globalcatalog.cloud.ibm.com
    • Washington DC: https://private.us-east.globalcatalog.cloud.ibm.com

Example API request

curl --request POST --header "content-type: application/json" --header "accept: application/json" --header "authorization: Bearer <IAM token>" --url 'https://globalcatalog.cloud.ibm.com/api/v1?account=string' --data '{"active":true,"catalog_crn":"string","children":[null],"children_url":"string","created":"string","disabled":true,"geo_tags":[null],"group":true,"id":"string"}'

Replace <IAM token> in this example with the value for your particular API call.

Authentication

Authorization to the Global Catalog API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

  • Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
  • By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_CATALOG_URL=<SERVICE_URL>
export GLOBAL_CATALOG_AUTHTYPE=iam
export GLOBAL_CATALOG_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/globalcatalogv1"
}
...
serviceClientOptions := &globalcatalogv1.GlobalCatalogV1Options{}
serviceClient, err := globalcatalogv1.NewGlobalCatalogV1UsingExternalConfig(serviceClientOptions)

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_CATALOG_URL=<SERVICE_URL>
export GLOBAL_CATALOG_AUTHTYPE=iam
export GLOBAL_CATALOG_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.global_catalog.v1.GlobalCatalog;
...
GlobalCatalog serviceClient = GlobalCatalog.newInstance();

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_CATALOG_URL=<SERVICE_URL>
export GLOBAL_CATALOG_AUTHTYPE=iam
export GLOBAL_CATALOG_APIKEY=<API_KEY>

Example of constructing the service client

const GlobalCatalogV1 = require('@ibm-cloud/platform-services/global-catalog/v1');
...
const serviceClient = GlobalCatalogV1.newInstance({});

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export GLOBAL_CATALOG_URL=<SERVICE_URL>
export GLOBAL_CATALOG_AUTHTYPE=iam
export GLOBAL_CATALOG_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import GlobalCatalogV1
...
service_client = GlobalCatalogV1.new_instance()

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.

Event tracking

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When some API methods are called, an event is generated that you can then track and audit from within Activity Tracker. For methods that generate events, the specific event type is listed for each individual method.

For more information about how to track activity in the Global Catalog, see Auditing events for account management.

Related APIs

Catalog Management API: Define the way users in your account can interact with the IBM Cloud catalog and the private catalogs that you've created.

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)
(globalCatalog *GlobalCatalogV1) ListCatalogEntriesWithContext(ctx context.Context, listCatalogEntriesOptions *ListCatalogEntriesOptions) (result *EntrySearchResult, response *core.DetailedResponse, err error)
ServiceCall<EntrySearchResult> listCatalogEntries(ListCatalogEntriesOptions listCatalogEntriesOptions)
listCatalogEntries(params)
list_catalog_entries(self,
        *,
        account: str = None,
        include: str = None,
        q: str = None,
        sort_by: str = None,
        descending: str = None,
        languages: str = None,
        catalog: bool = None,
        complete: bool = None,
        offset: int = None,
        limit: int = None,
        **kwargs
    ) -> DetailedResponse

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

  • account
    string

    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.

  • include
    string

    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.

  • q
    string

    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:

  • sort-by
    string

    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.

  • descending
    string

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

  • languages
    string

    Return the data strings in a specified language. By default, the strings returned are of the language preferred by your browser through the Accept-Language 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 (*).

  • catalog
    boolean

    Checks to see if a catalog's object is visible, or if it's filtered by service, plan, deployment, or region. Use the value ?catalog=true. If a 200 code is returned, the object is visible. If a 403 code is returned, the object is not visible for the user.

  • complete
    boolean

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

  • _offset
    integer

    Useful for pagination, specifies index (origin 0) of first item to return in response.

    Default: 0

  • _limit
    integer

    Useful for pagination, specifies the maximum number of items to return in the response.

    Possible values: value ≤ 200

    Default: 50

parameter

WithContext method only

ListCatalogEntriesOptions

The ListCatalogEntries options.

ListCatalogEntriesOptions

The listCatalogEntries options.

parameters

  • account
    string

    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.

  • include
    string

    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.

  • q
    string

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

  • sortBy
    string

    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.

  • descending
    string

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

  • languages
    string

    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 (*).

  • catalog
    boolean

    Checks to see if a catalog's object is visible, or if it's filtered by service, plan, deployment, or region. Use the value ?catalog=true. If a 200 code is returned, the object is visible. If a 403 code is returned, the object is not visible for the user.

  • complete
    boolean

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

  • offset
    number

    Useful for pagination, specifies index (origin 0) of first item to return in response.

  • limit
    number

    Useful for pagination, specifies the maximum number of items to return in the response.

    Possible values: value ≤ 200

parameters

  • account
    str

    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.

  • include
    str

    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.

  • q
    str

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

  • sort_by
    str

    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.

  • descending
    str

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

  • languages
    str

    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 (*).

  • catalog
    bool

    Checks to see if a catalog's object is visible, or if it's filtered by service, plan, deployment, or region. Use the value ?catalog=true. If a 200 code is returned, the object is visible. If a 403 code is returned, the object is not visible for the user.

  • complete
    bool

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

  • offset
    int

    Useful for pagination, specifies index (origin 0) of first item to return in response.

  • limit
    int

    Useful for pagination, specifies the maximum number of items to return in the response.

    Possible values: value ≤ 200

  • 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'
  • listCatalogEntriesOptions := globalCatalogService.NewListCatalogEntriesOptions()
listCatalogEntriesOptions.SetOffset(0)
listCatalogEntriesOptions.SetLimit(10)
listCatalogEntriesOptions.SetQ("kind:template tag:example-tag-1")
listCatalogEntriesOptions.SetComplete(true)

entrySearchResult, response, err := globalCatalogService.ListCatalogEntries(listCatalogEntriesOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(entrySearchResult, "", "  ")
fmt.Println(string(b))
  • ListCatalogEntriesOptions listCatalogEntriesOptions = new ListCatalogEntriesOptions.Builder()
    .offset(0)
    .limit(10)
    .q("kind:template tag:example-tag-1")
    .complete(true)
    .build();

Response<EntrySearchResult> response = service.listCatalogEntries(listCatalogEntriesOptions).execute();
EntrySearchResult entrySearchResult = response.getResult();

System.out.println(entrySearchResult);
  • const params = {
  offset: 0,
  limit: 10,
  q: 'kind:template tag:example-tag-1',
  complete: true,
};
globalCatalogService.listCatalogEntries(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • entry_search_result = global_catalog_service.list_catalog_entries(
  offset=0,
  limit=10,
  q='kind:template tag:example-tag-1',
  complete=True,
).get_result()

print(json.dumps(entry_search_result, indent=2))

Response

Response Body

EntrySearchResult

A paginated search result containing catalog entries.

EntrySearchResult

A paginated search result containing catalog entries.

EntrySearchResult

A paginated search result containing catalog entries.

EntrySearchResult

A paginated search result containing catalog entries.

EntrySearchResult

A paginated search result containing catalog entries.

Status Code

  • 200

    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)
(globalCatalog *GlobalCatalogV1) CreateCatalogEntryWithContext(ctx context.Context, createCatalogEntryOptions *CreateCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)
ServiceCall<CatalogEntry> createCatalogEntry(CreateCatalogEntryOptions createCatalogEntryOptions)
createCatalogEntry(params)
create_catalog_entry(self,
        name: str,
        kind: str,
        overview_ui: dict,
        images: 'Image',
        disabled: bool,
        tags: List[str],
        provider: 'Provider',
        id: str,
        *,
        parent_id: str = None,
        group: bool = None,
        active: bool = None,
        metadata: 'ObjectMetadataSet' = None,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

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

  • account
    string

    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.

Request Body

Required*
CatalogEntryCreate

The catalog entry to be created.

parameter

WithContext method only

CreateCatalogEntryOptions

The CreateCatalogEntry options.

CreateCatalogEntryOptions

The createCatalogEntry options.

parameters

  • name
    Required*
    string

    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.

  • kind
    Required*
    string

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

    Allowable values: [service,template,dashboard]

  • overviewUi
    Required*

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

  • images

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

  • disabled
    Required*
    boolean

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

  • tags
    Required*
    string[]

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

  • provider

    Information related to the provider associated with a catalog entry.

  • id
    Required*
    string

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

  • parentId
    string

    The ID of the parent catalog entry if it exists.

  • group
    boolean

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

  • active
    boolean

    Boolean value that describes whether the service is active.

  • metadata

    Model used to describe metadata object that can be set.

  • account
    string

    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

  • name
    Required*
    str

    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.

  • kind
    Required*
    str

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

    Allowable values: [service,template,dashboard]

  • overview_ui
    Required*

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

  • images

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

  • disabled
    Required*
    bool

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

  • tags
    Required*
    List[str]

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

  • provider

    Information related to the provider associated with a catalog entry.

  • id
    Required*
    str

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

  • parent_id
    str

    The ID of the parent catalog entry if it exists.

  • group
    bool

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

  • active
    bool

    Boolean value that describes whether the service is active.

  • metadata

    Model used to describe metadata object that can be set.

  • account
    str

    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":"integer","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"}'
  • displayName := "Example Web Starter"
description := "Use the Example service in your applications"
longDescription := "This is a starter that helps you use the Example service within your applications."
overviewModelEN := &globalcatalogv1.Overview{
  DisplayName:     &displayName,
  Description:     &description,
  LongDescription: &longDescription,
}
overviewUIModel := make(map[string]globalcatalogv1.Overview)
overviewUIModel["en"] = *overviewModelEN

smallImageURL := "https://somehost.com/examplewebstarter/cachedIcon/small/0"
mediumImageURL := "https://somehost.com/examplewebstarter/cachedIcon/medium/0"
largeImageURL := "https://somehost.com/examplewebstarter/cachedIcon/large/0"
imageModel := &globalcatalogv1.Image{
  Image:        &largeImageURL,
  SmallImage:   &smallImageURL,
  MediumImage:  &mediumImageURL,
  FeatureImage: &largeImageURL,
}

providerModel := &globalcatalogv1.Provider{
  Email:        core.StringPtr("info@examplestarter.com"),
  Name:         core.StringPtr("Example Starter Co., Inc."),
  Contact:      core.StringPtr("Example Starter Developer Relations"),
  SupportEmail: core.StringPtr("support@examplestarter.com"),
  Phone:        core.StringPtr("800-555-1234"),
}

metadataModel := &globalcatalogv1.ObjectMetadataSet{
  Version: core.StringPtr("1.0.0"),
}

catalogEntryID = uuid.New().String()

createCatalogEntryOptions := globalCatalogService.NewCreateCatalogEntryOptions(
  "exampleWebStarter123",
  globalcatalogv1.CreateCatalogEntryOptionsKindTemplateConst,
  overviewUIModel,
  imageModel,
  false,
  []string{"example-tag-1", "example-tag-2"},
  providerModel,
  catalogEntryID,
)
createCatalogEntryOptions.SetActive(true)
createCatalogEntryOptions.SetMetadata(metadataModel)

catalogEntry, response, err := globalCatalogService.CreateCatalogEntry(createCatalogEntryOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(catalogEntry, "", "  ")
fmt.Println(string(b))
  • Overview overviewModelEN = new Overview.Builder()
    .displayName("Example Web Starter")
    .description("Use the Example service in your applications")
    .longDescription("This is a starter that helps you use the Example service within your applications.")
    .build();
Map<String, Overview> overviewUI = new HashMap<>();
overviewUI.put("en", overviewModelEN);

Image imageModel = new Image.Builder()
    .image("https://somehost.com/examplewebstarter/cachedIcon/large/0")
    .smallImage("https://somehost.com/examplewebstarter/cachedIcon/small/0")
    .mediumImage("https://somehost.com/examplewebstarter/cachedIcon/medium/0")
    .featureImage("https://somehost.com/examplewebstarter/cachedIcon/large/0")
    .build();

Provider providerModel = new Provider.Builder()
    .email("info@examplestarter.com")
    .name("Example Starter Co., Inc.")
    .contact("Example Starter Developer Relations")
    .supportEmail("support@examplestarter.com")
    .phone("800-555-1234")
    .build();

ObjectMetadataSet metadataModel = new ObjectMetadataSet.Builder()
    .version("1.0.0")
    .build();

catalogEntryId = UUID.randomUUID().toString();

CreateCatalogEntryOptions createCatalogEntryOptions = new CreateCatalogEntryOptions.Builder()
    .name("exampleWebStarter123")
    .kind(CreateCatalogEntryOptions.Kind.TEMPLATE)
    .overviewUi(overviewUI)
    .images(imageModel)
    .disabled(false)
    .addTags("example-tag-1")
    .addTags("example-tag-2")
    .provider(providerModel)
    .id(catalogEntryId)
    .active(true)
    .metadata(metadataModel)
    .build();

Response<CatalogEntry> response = service.createCatalogEntry(createCatalogEntryOptions).execute();
CatalogEntry catalogEntry = response.getResult();

System.out.println(catalogEntry);
  • const overviewModelEN = {
  display_name: 'Example Web Starter',
  description: 'Use the Example service in your applications',
  long_description: 'This is a starter that helps you use the Example service within your applications.',
};
const overviewUIModel = {
  en: overviewModelEN,
};
const imageModel = {
  image: 'https://somehost.com/examplewebstarter/cachedIcon/large/0',
  small_image: 'https://somehost.com/examplewebstarter/cachedIcon/small/0',
  medium_image: 'https://somehost.com/examplewebstarter/cachedIcon/medium/0',
  feature_image: 'https://somehost.com/examplewebstarter/cachedIcon/large/0',
};
const providerModel = {
  email: 'info@examplestarter.com',
  name: 'Example Starter Co., Inc.',
  contact: 'Example Starter Developer Relations',
  support_email: 'support@examplestarter.com',
  phone: '800-555-1234',
};
const metadataModel = {
  version: '1.0.0',
};

catalogEntryId = uuidv4();

const params = {
  name: 'exampleWebStarter123',
  kind: CreateCatalogEntryConstants.Kind.TEMPLATE,
  overviewUi: overviewUIModel,
  images: imageModel,
  disabled: false,
  tags: ['example-tag-1', 'example-tag-2'],
  provider: providerModel,
  id: catalogEntryId,
  active: true,
  metadata: metadataModel,
};

globalCatalogService.createCatalogEntry(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
  • overview_model_EN = {
  'display_name': 'Example Web Starter',
  'description': 'Use the Example service in your applications',
  'long_description': 'This is a starter that helps you use the Example service within your applications.',
}
image_model = {
  'image': 'https://somehost.com/examplewebstarter/cachedIcon/large/0',
  'small_image': 'https://somehost.com/examplewebstarter/cachedIcon/small/0',
  'medium_image': 'https://somehost.com/examplewebstarter/cachedIcon/medium/0',
  'feature_image': 'https://somehost.com/examplewebstarter/cachedIcon/large/0',
}
provider_model = {
  'email': 'info@examplestarter.com',
  'name': 'Example Starter Co., Inc.',
  'contact': 'Example Starter Developer Relations',
  'support_email': 'support@examplestarter.com',
  'phone': '800-555-1234',
}
metadata_model = {
  'version': '1.0.0',
}
catalog_entry_id = str(uuid.uuid4())

catalog_entry = global_catalog_service.create_catalog_entry(
  name='exampleWebStarter123',
  kind=CatalogEntry.KindEnum.TEMPLATE,
  overview_ui={
    'en': overview_model_EN
  },
  images=image_model,
  disabled=False,
  tags=['example-tag-1', 'example-tag-2'],
  provider=provider_model,
  id=catalog_entry_id,
  active=True,
  metadata=metadata_model,
).get_result()

print(json.dumps(catalog_entry, indent=2))

Response

Response Body

CatalogEntry

An entry in the global catalog.

CatalogEntry

An entry in the global catalog.

CatalogEntry

An entry in the global catalog.