Global Catalog API | IBM Cloud API Docs

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.

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.

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

parameter

WithContext method only

ListCatalogEntriesOptions

The ListCatalogEntries options.

ListCatalogEntriesOptions

The listCatalogEntries options.

parameters

Example request

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'

Example request

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))

Example request

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);

Example request

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)
  });

Example request

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

Status 200

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

Success example

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

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.

Example request

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"}'

Example request

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))

Example request

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);

Example request

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)
  });

Example request

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.

CatalogEntry

An entry in the global catalog.

CatalogEntry

An entry in the global catalog.

Status Code

201
Successfully created a catalog entry.
400
The request was invalid. Such as invalid depth query parameter.
401
Unauthorized
403
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.

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 can be used by an unauthenticated user for publicly available services.

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 can be used by an unauthenticated user for publicly available services.

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 can be used by an unauthenticated user for publicly available services.

GET /{id}

(globalCatalog *GlobalCatalogV1) GetCatalogEntry(getCatalogEntryOptions *GetCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetCatalogEntryWithContext(ctx context.Context, getCatalogEntryOptions *GetCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)

ServiceCall<CatalogEntry> getCatalogEntry(GetCatalogEntryOptions getCatalogEntryOptions)

getCatalogEntry(params)

get_catalog_entry(self,
        id: str,
        *,
        account: str = None,
        include: str = None,
        languages: str = None,
        complete: bool = None,
        depth: int = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetCatalogEntryOptions struct and set the fields to provide parameter values for the GetCatalogEntry method.

Use the GetCatalogEntryOptions.Builder to create a GetCatalogEntryOptions object that contains the parameter values for the getCatalogEntry method.

Path Parameters

id
Required*
string
The catalog entry's unique ID

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 /id?include=*. To include specific metadata fields, separate each field with a colon (:), for example GET /id?include=metadata.ui:metadata.pricing.
languages
string
Return the data strings in the 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 (*).
complete
boolean
Returns all available fields for all languages. Use the value ?complete=true as shortcut for ?include=&languages=.
depth
integer
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.

parameter

WithContext method only

GetCatalogEntryOptions

The GetCatalogEntry options.

GetCatalogEntryOptions

The getCatalogEntry options.

parameters

id
Required*
string
The catalog entry's unqiue ID.
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 /id?include=*. To include specific metadata fields, separate each field with a colon (:), for example GET /id?include=metadata.ui:metadata.pricing.
languages
string
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 (*).
complete
boolean
Returns all available fields for all languages. Use the value ?complete=true as shortcut for ?include=&languages=.
depth
number
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.

parameters

id
Required*
str
The catalog entry's unqiue ID.
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 /id?include=*. To include specific metadata fields, separate each field with a colon (:), for example GET /id?include=metadata.ui:metadata.pricing.
languages
str
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 (*).
complete
bool
Returns all available fields for all languages. Use the value ?complete=true as shortcut for ?include=&languages=.
depth
int
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 request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}?account=string&include=string&languages=string&complete=string&depth=0' --header 'accept: application/json'

Example request

getCatalogEntryOptions := globalCatalogService.NewGetCatalogEntryOptions(
  catalogEntryID,
)
getCatalogEntryOptions.SetComplete(true)

catalogEntry, response, err := globalCatalogService.GetCatalogEntry(getCatalogEntryOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(catalogEntry, "", "  ")
fmt.Println(string(b))

Example request

GetCatalogEntryOptions getCatalogEntryOptions = new GetCatalogEntryOptions.Builder()
    .id(catalogEntryId)
    .complete(true)
    .build();

Response<CatalogEntry> response = service.getCatalogEntry(getCatalogEntryOptions).execute();
CatalogEntry catalogEntry = response.getResult();

System.out.println(catalogEntry);

Example request

const params = {
  id: catalogEntryId,
  complete: true,
};

globalCatalogService.getCatalogEntry(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

catalog_entry = global_catalog_service.get_catalog_entry(
  id=catalog_entry_id,
  complete=True,
).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.

CatalogEntry

An entry in the global catalog.

CatalogEntry

An entry in the global catalog.

Status Code

200
A catalog entry object
401
Unauthorized
403
No Permissions
404
Object was not found.

Example responses

Status 200

{
  "active": "BOOLEAN",
  "catalog_crn": "STRING",
  "children": "ARRAY",
  "children_url": "STRING",
  "created": "STRING",
  "disabled": "BOOLEAN",
  "geo_tags": "ARRAY",
  "group": "BOOLEAN",
  "id": "STRING",
  "images": {
    "feature_image": "STRING",
    "image": "STRING",
    "medium_image": "STRING",
    "small_image": "STRING"
  },
  "kind": "STRING",
  "metadata": {
    "alias": {
      "plan_id": "STRING",
      "type": "STRING"
    },
    "callbacks": {
      "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"
    },
    "compliance": "ARRAY",
    "deployment": {
      "broker": {
        "guid": "STRING",
        "name": "STRING",
        "password": {
          "iv": "STRING",
          "key": "STRING",
          "text": "STRING"
        }
      },
      "location": "STRING",
      "location_url": "STRING",
      "supports_rc_migration": "BOOLEAN",
      "target_crn": "STRING"
    },
    "origin_name": "STRING",
    "other": "OBJECT",
    "plan": {
      "allow_internal_users": "BOOLEAN",
      "async_provisioning_supported": "BOOLEAN",
      "async_unprovisioning_supported": "BOOLEAN",
      "bindable": "BOOLEAN",
      "cf_guid": "STRING",
      "reservable": "BOOLEAN",
      "service_check_enabled": "BOOLEAN",
      "single_scope_instance": "STRING",
      "test_check_interval": "INTEGER"
    },
    "pricing": {
      "metrics": {
        "amounts": {
          "country": "STRING",
          "currency": "STRING",
          "prices": {
            "price": "DOUBLE",
            "quantity_tier": "INTEGER"
          }
        },
        "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": "INTEGER"
      },
      "origin": "STRING",
      "starting_price": {
        "amount": {
          "country": "STRING",
          "currency": "STRING",
          "prices": {
            "price": "DOUBLE",
            "quantity_tier": "INTEGER"
          }
        },
        "deployment_id": "STRING",
        "plan_id": "STRING"
      },
      "type": "STRING"
    },
    "rc_compatible": "BOOLEAN",
    "service": {
      "async_provisioning_supported": "BOOLEAN",
      "async_unprovisioning_supported": "BOOLEAN",
      "bindable": "BOOLEAN",
      "cf_guid": "STRING",
      "iam_compatible": "BOOLEAN",
      "plan_updateable": "BOOLEAN",
      "provisionable": "BOOLEAN",
      "requires": "ARRAY",
      "service_check_enabled": "BOOLEAN",
      "service_key_supported": "BOOLEAN",
      "state": "STRING",
      "test_check_interval": "INTEGER",
      "type": "STRING",
      "unique_api_key": "BOOLEAN"
    },
    "sla": {
      "dr": {
        "description": "STRING",
        "dr": "BOOLEAN"
      },
      "provisioning": "NUMBER",
      "responsiveness": "NUMBER",
      "tenancy": "STRING",
      "terms": "STRING"
    },
    "template": {
      "buildpack": "STRING",
      "cf_runtime_id": "STRING",
      "default_memory": "INTEGER",
      "environment_variables": {
        "_key_": "STRING"
      },
      "executable_file": "STRING",
      "runtime_catalog_id": "STRING",
      "services": "ARRAY",
      "source": {
        "path": "STRING",
        "type": "STRING",
        "url": "STRING"
      },
      "start_cmd": "STRING",
      "template_id": "STRING"
    },
    "ui": {
      "accessible_during_provision": "BOOLEAN",
      "embeddable_dashboard": "STRING",
      "embeddable_dashboard_full_width": "BOOLEAN",
      "end_of_service_time": "STRING",
      "navigation_order": "ARRAY",
      "not_creatable": "BOOLEAN",
      "primary_offering_id": "STRING",
      "reservable": "BOOLEAN",
      "side_by_side_index": "INTEGER",
      "strings": {
        "_language_": {
          "bullets": {
            "description": "STRING",
            "icon": "STRING",
            "quantity": "STRING",
            "title": "STRING"
          },
          "deprecation_warning": "STRING",
          "instruction": "STRING",
          "media": {
            "URL": "STRING",
            "caption": "STRING",
            "source": {
              "description": "STRING",
              "icon": "STRING",
              "quantity": "STRING",
              "title": "STRING"
            },
            "thumbnail_url": "STRING",
            "type": "STRING"
          },
          "not_creatable__robot_msg": "STRING",
          "not_creatable_msg": "STRING",
          "popup_warning_message": "STRING"
        }
      },
      "urls": {
        "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"
      }
    },
    "version": "STRING"
  },
  "name": "STRING",
  "overview_ui": {
    "_language_": {
      "description": "STRING",
      "display_name": "STRING",
      "long_description": "STRING"
    }
  },
  "parent_id": "STRING",
  "parent_url": "STRING",
  "pricing_tags": "ARRAY",
  "provider": {
    "contact": "STRING",
    "email": "STRING",
    "name": "STRING",
    "phone": "STRING",
    "support_email": "STRING"
  },
  "tags": "ARRAY",
  "updated": "STRING",
  "url": "STRING"
}

Success example

{
  "active": "BOOLEAN",
  "catalog_crn": "STRING",
  "children": "ARRAY",
  "children_url": "STRING",
  "created": "STRING",
  "disabled": "BOOLEAN",
  "geo_tags": "ARRAY",
  "group": "BOOLEAN",
  "id": "STRING",
  "images": {
    "feature_image": "STRING",
    "image": "STRING",
    "medium_image": "STRING",
    "small_image": "STRING"
  },
  "kind": "STRING",
  "metadata": {
    "alias": {
      "plan_id": "STRING",
      "type": "STRING"
    },
    "callbacks": {
      "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"
    },
    "compliance": "ARRAY",
    "deployment": {
      "broker": {
        "guid": "STRING",
        "name": "STRING",
        "password": {
          "iv": "STRING",
          "key": "STRING",
          "text": "STRING"
        }
      },
      "location": "STRING",
      "location_url": "STRING",
      "supports_rc_migration": "BOOLEAN",
      "target_crn": "STRING"
    },
    "origin_name": "STRING",
    "other": "OBJECT",
    "plan": {
      "allow_internal_users": "BOOLEAN",
      "async_provisioning_supported": "BOOLEAN",
      "async_unprovisioning_supported": "BOOLEAN",
      "bindable": "BOOLEAN",
      "cf_guid": "STRING",
      "reservable": "BOOLEAN",
      "service_check_enabled": "BOOLEAN",
      "single_scope_instance": "STRING",
      "test_check_interval": "INTEGER"
    },
    "pricing": {
      "metrics": {
        "amounts": {
          "country": "STRING",
          "currency": "STRING",
          "prices": {
            "price": "DOUBLE",
            "quantity_tier": "INTEGER"
          }
        },
        "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": "INTEGER"
      },
      "origin": "STRING",
      "starting_price": {
        "amount": {
          "country": "STRING",
          "currency": "STRING",
          "prices": {
            "price": "DOUBLE",
            "quantity_tier": "INTEGER"
          }
        },
        "deployment_id": "STRING",
        "plan_id": "STRING"
      },
      "type": "STRING"
    },
    "rc_compatible": "BOOLEAN",
    "service": {
      "async_provisioning_supported": "BOOLEAN",
      "async_unprovisioning_supported": "BOOLEAN",
      "bindable": "BOOLEAN",
      "cf_guid": "STRING",
      "iam_compatible": "BOOLEAN",
      "plan_updateable": "BOOLEAN",
      "provisionable": "BOOLEAN",
      "requires": "ARRAY",
      "service_check_enabled": "BOOLEAN",
      "service_key_supported": "BOOLEAN",
      "state": "STRING",
      "test_check_interval": "INTEGER",
      "type": "STRING",
      "unique_api_key": "BOOLEAN"
    },
    "sla": {
      "dr": {
        "description": "STRING",
        "dr": "BOOLEAN"
      },
      "provisioning": "NUMBER",
      "responsiveness": "NUMBER",
      "tenancy": "STRING",
      "terms": "STRING"
    },
    "template": {
      "buildpack": "STRING",
      "cf_runtime_id": "STRING",
      "default_memory": "INTEGER",
      "environment_variables": {
        "_key_": "STRING"
      },
      "executable_file": "STRING",
      "runtime_catalog_id": "STRING",
      "services": "ARRAY",
      "source": {
        "path": "STRING",
        "type": "STRING",
        "url": "STRING"
      },
      "start_cmd": "STRING",
      "template_id": "STRING"
    },
    "ui": {
      "accessible_during_provision": "BOOLEAN",
      "embeddable_dashboard": "STRING",
      "embeddable_dashboard_full_width": "BOOLEAN",
      "end_of_service_time": "STRING",
      "navigation_order": "ARRAY",
      "not_creatable": "BOOLEAN",
      "primary_offering_id": "STRING",
      "reservable": "BOOLEAN",
      "side_by_side_index": "INTEGER",
      "strings": {
        "_language_": {
          "bullets": {
            "description": "STRING",
            "icon": "STRING",
            "quantity": "STRING",
            "title": "STRING"
          },
          "deprecation_warning": "STRING",
          "instruction": "STRING",
          "media": {
            "URL": "STRING",
            "caption": "STRING",
            "source": {
              "description": "STRING",
              "icon": "STRING",
              "quantity": "STRING",
              "title": "STRING"
            },
            "thumbnail_url": "STRING",
            "type": "STRING"
          },
          "not_creatable__robot_msg": "STRING",
          "not_creatable_msg": "STRING",
          "popup_warning_message": "STRING"
        }
      },
      "urls": {
        "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"
      }
    },
    "version": "STRING"
  },
  "name": "STRING",
  "overview_ui": {
    "_language_": {
      "description": "STRING",
      "display_name": "STRING",
      "long_description": "STRING"
    }
  },
  "parent_id": "STRING",
  "parent_url": "STRING",
  "pricing_tags": "ARRAY",
  "provider": {
    "contact": "STRING",
    "email": "STRING",
    "name": "STRING",
    "phone": "STRING",
    "support_email": "STRING"
  },
  "tags": "ARRAY",
  "updated": "STRING",
  "url": "STRING"
}

Update a catalog entry. The visibility of the catalog entry 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}

(globalCatalog *GlobalCatalogV1) UpdateCatalogEntry(updateCatalogEntryOptions *UpdateCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) UpdateCatalogEntryWithContext(ctx context.Context, updateCatalogEntryOptions *UpdateCatalogEntryOptions) (result *CatalogEntry, response *core.DetailedResponse, err error)

ServiceCall<CatalogEntry> updateCatalogEntry(UpdateCatalogEntryOptions updateCatalogEntryOptions)

updateCatalogEntry(params)

update_catalog_entry(self,
        id: str,
        name: str,
        kind: str,
        overview_ui: dict,
        images: 'Image',
        disabled: bool,
        tags: List[str],
        provider: 'Provider',
        *,
        parent_id: str = None,
        group: bool = None,
        active: bool = None,
        metadata: 'ObjectMetadataSet' = None,
        account: str = None,
        move: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the UpdateCatalogEntryOptions struct and set the fields to provide parameter values for the UpdateCatalogEntry method.

Use the UpdateCatalogEntryOptions.Builder to create a UpdateCatalogEntryOptions object that contains the parameter values for the updateCatalogEntry method.

Path Parameters

id
Required*
string
The object's unique ID

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.
move
string
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.

Request Body

Required*

CatalogEntryUpdate

The catalog entry to be updated.

parameter

WithContext method only

UpdateCatalogEntryOptions

The UpdateCatalogEntry options.

UpdateCatalogEntryOptions

The updateCatalogEntry options.

parameters

id
Required*
string
The object's unique ID.
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.
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.
move
string
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.

parameters

id
Required*
str
The object's unique ID.
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.
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.
move
str
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.

Example request

curl --request PUT --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}?account=string&move=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"}'

Example request

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

updateCatalogEntryOptions := globalCatalogService.NewUpdateCatalogEntryOptions(
  catalogEntryID,
  "exampleWebStarter123",
  globalcatalogv1.UpdateCatalogEntryOptionsKindTemplateConst,
  overviewUI,
  imageModel,
  false,
  []string{"example-tag-1", "example-tag-2", "new-example-tag-3"},
  providerModel,
)
updateCatalogEntryOptions.SetActive(true)
updateCatalogEntryOptions.SetMetadata(metadataModel)

catalogEntry, response, err := globalCatalogService.UpdateCatalogEntry(updateCatalogEntryOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(catalogEntry, "", "  ")
fmt.Println(string(b))

Example request

Overview overviewModelEN = new Overview.Builder()
    .displayName("Example Web Starter V2")
    .description("Use the Example V2 service in your applications")
    .longDescription("This is a starter that helps you use the Example V2 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("2.0.0")
    .build();

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

Response<CatalogEntry> response = service.updateCatalogEntry(updateCatalogEntryOptions).execute();
CatalogEntry catalogEntry = response.getResult();

System.out.println(catalogEntry);

Example request

const overviewModelEN = {
  display_name: 'Example Web Starter V2',
  description: 'Use the Example V2 service in your applications',
  long_description: 'This is a starter that helps you use the Example V2 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: '2.0.0',
};

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

globalCatalogService.updateCatalogEntry(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

overview_model_EN = {
  'display_name': 'Example Web Starter V2',
  'description': 'Use the Example V2 service in your applications',
  'long_description': 'This is a starter that helps you use the Example V2 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': '2.0.0',
}

catalog_entry = global_catalog_service.update_catalog_entry(
  id=catalog_entry_id,
  name='exampleWebStarter123',
  kind=CatalogEntry.KindEnum.TEMPLATE,
  overview_ui={
    'en': overview_model_EN,
  },
  images=image_model,
  disabled=False,
  tags=['example-tag-1', 'example-tag-2', 'new-example-tag-3'],
  provider=provider_model,
  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.

CatalogEntry

An entry in the global catalog.

CatalogEntry

An entry in the global catalog.

Status Code

200
Successfully updated the catalog entry.
400
There is a validation error. Use accept=application/json to see all of the validation errors.
401
Unauthorized.
403
Permission Denied: You must have an Adminstrator or editor role to update this catalog entry.
404
Object was not found.

No Sample Response

This method does not specify any sample responses.

Delete a catalog entry. This will archive the catalog 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}

(globalCatalog *GlobalCatalogV1) DeleteCatalogEntry(deleteCatalogEntryOptions *DeleteCatalogEntryOptions) (response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) DeleteCatalogEntryWithContext(ctx context.Context, deleteCatalogEntryOptions *DeleteCatalogEntryOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteCatalogEntry(DeleteCatalogEntryOptions deleteCatalogEntryOptions)

deleteCatalogEntry(params)

delete_catalog_entry(self,
        id: str,
        *,
        account: str = None,
        force: bool = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the DeleteCatalogEntryOptions struct and set the fields to provide parameter values for the DeleteCatalogEntry method.

Use the DeleteCatalogEntryOptions.Builder to create a DeleteCatalogEntryOptions object that contains the parameter values for the deleteCatalogEntry method.

Path Parameters

id
Required*
string
The object's unique ID

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.
force
boolean
This will cause entry to be deleted fully. By default it is archived for two weeks, so that it can be restored if necessary.

parameter

WithContext method only

DeleteCatalogEntryOptions

The DeleteCatalogEntry options.

DeleteCatalogEntryOptions

The deleteCatalogEntry options.

parameters

id
Required*
string
The object's unique ID.
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.
force
boolean
This will cause entry to be deleted fully. By default it is archived for two weeks, so that it can be restored if necessary.

parameters

id
Required*
str
The object's unique ID.
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.
force
bool
This will cause entry to be deleted fully. By default it is archived for two weeks, so that it can be restored if necessary.

Example request

curl --request DELETE --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}?account=string' --header 'accept: application/json'

Example request

deleteCatalogEntryOptions := globalCatalogService.NewDeleteCatalogEntryOptions(
  catalogEntryID,
)

response, err := globalCatalogService.DeleteCatalogEntry(deleteCatalogEntryOptions)
if err != nil {
  panic(err)
}

Example request

DeleteCatalogEntryOptions deleteCatalogEntryOptions = new DeleteCatalogEntryOptions.Builder()
    .id(catalogEntryId)
    .build();

service.deleteCatalogEntry(deleteCatalogEntryOptions).execute();

Example request

const params = {
  id: catalogEntryId,
};

globalCatalogService.deleteCatalogEntry(params)
  .then(res => {
    console.log(JSON.stringify(res, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = global_catalog_service.delete_catalog_entry(
  id=catalog_entry_id).get_result()

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

Response

Status Code

200
Successfully deleted the catalog entry, or it was already archived or did not exist.
401
Unauthorized.
403
Permission Denied: You must have an Adminstrator role to create a catalog entry.

No Sample Response

This method does not specify any sample responses.

Fetch child catalog entries for a catalog entry with a specific id. This endpoint is ETag enabled. This can be used by an unauthenticated user for publicly available services.

GET /{id}/{kind}

(globalCatalog *GlobalCatalogV1) GetChildObjects(getChildObjectsOptions *GetChildObjectsOptions) (result *EntrySearchResult, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetChildObjectsWithContext(ctx context.Context, getChildObjectsOptions *GetChildObjectsOptions) (result *EntrySearchResult, response *core.DetailedResponse, err error)

ServiceCall<EntrySearchResult> getChildObjects(GetChildObjectsOptions getChildObjectsOptions)

getChildObjects(params)

get_child_objects(self,
        id: str,
        kind: str,
        *,
        account: str = None,
        include: str = None,
        q: str = None,
        sort_by: str = None,
        descending: str = None,
        languages: str = None,
        complete: bool = None,
        offset: int = None,
        limit: int = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetChildObjectsOptions struct and set the fields to provide parameter values for the GetChildObjects method.

Use the GetChildObjectsOptions.Builder to create a GetChildObjectsOptions object that contains the parameter values for the getChildObjects method.

Path Parameters

id
Required*
string
The parent catalog entry's ID
kind
Required*
string
The kind of child catalog entries to search for. A wildcard (*) includes all child catalog entries for all kinds, for example GET /service_name/*.

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 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
q
string
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.
sort-by
string
The field on which to sort the output. By default by name. Available fields are name, kind, and provider.
descending
string
The sort order. The default is false, which is ascending.
languages
string
Return the data strings in the specified language. By default the strings returned are of the language preferred by your browser through the Accept-Language 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 (*).
complete
boolean
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

GetChildObjectsOptions

The GetChildObjects options.

GetChildObjectsOptions

The getChildObjects options.

parameters

id
Required*
string
The parent catalog entry's ID.
kind
Required*
string
The kind of child catalog entries to search for. A wildcard (*) includes all child catalog entries for all kinds, for example GET /service_name/_*.
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 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.
q
string
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.
sortBy
string
The field on which to sort the output. By default by name. Available fields are name, kind, and provider.
descending
string
The sort order. The default is false, which is ascending.
languages
string
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 (*).
complete
boolean
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

id
Required*
str
The parent catalog entry's ID.
kind
Required*
str
The kind of child catalog entries to search for. A wildcard (*) includes all child catalog entries for all kinds, for example GET /service_name/*.
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 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.
q
str
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.
sort_by
str
The field on which to sort the output. By default by name. Available fields are name, kind, and provider.
descending
str
The sort order. The default is false, which is ascending.
languages
str
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 (*).
complete
bool
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

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/{kind}?account=string&include=string&q=string&sort-by=string&descending=string&languages=string&complete=string' --header 'accept: application/json'

Example request

getChildObjectsOptions := globalCatalogService.NewGetChildObjectsOptions(
  catalogEntryID,
  "*",
)
getChildObjectsOptions.SetOffset(0)
getChildObjectsOptions.SetLimit(10)
getChildObjectsOptions.SetComplete(true)

entrySearchResult, response, err := globalCatalogService.GetChildObjects(getChildObjectsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(entrySearchResult, "", "  ")
fmt.Println(string(b))

Example request

GetChildObjectsOptions getChildObjectsOptions = new GetChildObjectsOptions.Builder()
    .id(catalogEntryId)
    .kind("*")
    .build();

Response<EntrySearchResult> response = service.getChildObjects(getChildObjectsOptions).execute();
EntrySearchResult entrySearchResult = response.getResult();

System.out.println(entrySearchResult);

Example request

const params = {
  id: catalogEntryId,
  kind: '*',
  offset: 0,
  limit: 10,
  complete: true,
};

globalCatalogService.getChildObjects(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

entry_search_result = global_catalog_service.get_child_objects(
  id=catalog_entry_id,
  kind='*',
  offset=0,
  limit=10,
  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 child objects.

Example responses

Status 200

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

Success example

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

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

PUT /{id}/restore

(globalCatalog *GlobalCatalogV1) RestoreCatalogEntry(restoreCatalogEntryOptions *RestoreCatalogEntryOptions) (response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) RestoreCatalogEntryWithContext(ctx context.Context, restoreCatalogEntryOptions *RestoreCatalogEntryOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> restoreCatalogEntry(RestoreCatalogEntryOptions restoreCatalogEntryOptions)

restoreCatalogEntry(params)

restore_catalog_entry(self,
        id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the RestoreCatalogEntryOptions struct and set the fields to provide parameter values for the RestoreCatalogEntry method.

Use the RestoreCatalogEntryOptions.Builder to create a RestoreCatalogEntryOptions object that contains the parameter values for the restoreCatalogEntry method.

Path Parameters

id
Required*
string
The catalog entry's unique ID

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.

parameter

WithContext method only

RestoreCatalogEntryOptions

The RestoreCatalogEntry options.

RestoreCatalogEntryOptions

The restoreCatalogEntry options.

parameters

id
Required*
string
The catalog entry's unique ID.
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

id
Required*
str
The catalog entry's unique ID.
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.

Example request

curl --request PUT --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/restore?account=string' --header 'accept: application/json'

Example request

restoreCatalogEntryOptions := globalCatalogService.NewRestoreCatalogEntryOptions(
  catalogEntryID,
)

response, err := globalCatalogService.RestoreCatalogEntry(restoreCatalogEntryOptions)
if err != nil {
  panic(err)
}

Example request

RestoreCatalogEntryOptions restoreCatalogEntryOptions = new RestoreCatalogEntryOptions.Builder()
    .id(catalogEntryId)
    .build();

service.restoreCatalogEntry(restoreCatalogEntryOptions).execute();

Example request

const params = {
  id: catalogEntryId,
};

globalCatalogService.restoreCatalogEntry(params)
  .then(res => {
    console.log(JSON.stringify(res, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = global_catalog_service.restore_catalog_entry(
  id=catalog_entry_id,
).get_result()

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

Response

Status Code

200
Successfully restored the catalog entry.
401
Unauthorized
403
Permission Denied: You must have an Adminstrator role to set visibility of a catalog entry.
404
Object was not found.

No Sample Response

This method does not specify any sample responses.

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

(globalCatalog *GlobalCatalogV1) GetVisibility(getVisibilityOptions *GetVisibilityOptions) (result *Visibility, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetVisibilityWithContext(ctx context.Context, getVisibilityOptions *GetVisibilityOptions) (result *Visibility, response *core.DetailedResponse, err error)

ServiceCall<Visibility> getVisibility(GetVisibilityOptions getVisibilityOptions)

getVisibility(params)

get_visibility(self,
        id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetVisibilityOptions struct and set the fields to provide parameter values for the GetVisibility method.

Use the GetVisibilityOptions.Builder to create a GetVisibilityOptions object that contains the parameter values for the getVisibility method.

Path Parameters

id
Required*
string
The object's unique ID

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.

parameter

WithContext method only

GetVisibilityOptions

The GetVisibility options.

GetVisibilityOptions

The getVisibility options.

parameters

id
Required*
string
The object's unique ID.
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

id
Required*
str
The object's unique ID.
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.

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/visibility?account=string' --header 'accept: application/json'

Example request

getVisibilityOptions := globalCatalogService.NewGetVisibilityOptions(
  catalogEntryID,
)

visibility, response, err := globalCatalogService.GetVisibility(getVisibilityOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(visibility, "", "  ")
fmt.Println(string(b))

Example request

GetVisibilityOptions getVisibilityOptions = new GetVisibilityOptions.Builder()
    .id(catalogEntryId)
    .build();

Response<Visibility> response = service.getVisibility(getVisibilityOptions).execute();
Visibility visibility = response.getResult();

System.out.println(visibility);

Example request

const params = {
  id: catalogEntryId,
};

globalCatalogService.getVisibility(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

visibility = global_catalog_service.get_visibility(
  id=catalog_entry_id,
).get_result()

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

Response

Response Body

Visibility

Information related to the visibility of a catalog entry

Visibility

Information related to the visibility of a catalog entry.

Visibility

Information related to the visibility of a catalog entry.

Visibility

Information related to the visibility of a catalog entry.

Visibility

Information related to the visibility of a catalog entry.

Status Code

200
The entry visibility object
401
Unauthorized
403
No Permissions
404
Object was not found

Example responses

Status 200

{
  "approved": "BOOLEAN",
  "exclude": {
    "accounts": {
      "_accountid_": "STRING"
    }
  },
  "include": {
    "accounts": {
      "_accountid_": "STRING"
    }
  },
  "owner": "STRING",
  "restrictions": "STRING"
}

Success example

{
  "approved": "BOOLEAN",
  "exclude": {
    "accounts": {
      "_accountid_": "STRING"
    }
  },
  "include": {
    "accounts": {
      "_accountid_": "STRING"
    }
  },
  "owner": "STRING",
  "restrictions": "STRING"
}

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

(globalCatalog *GlobalCatalogV1) UpdateVisibility(updateVisibilityOptions *UpdateVisibilityOptions) (response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) UpdateVisibilityWithContext(ctx context.Context, updateVisibilityOptions *UpdateVisibilityOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> updateVisibility(UpdateVisibilityOptions updateVisibilityOptions)

updateVisibility(params)

update_visibility(self,
        id: str,
        *,
        extendable: bool = None,
        include: 'VisibilityDetail' = None,
        exclude: 'VisibilityDetail' = None,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the UpdateVisibilityOptions struct and set the fields to provide parameter values for the UpdateVisibility method.

Use the UpdateVisibilityOptions.Builder to create a UpdateVisibilityOptions object that contains the parameter values for the updateVisibility method.

Path Parameters

id
Required*
string
The object's unique ID

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*

Visibility

Object to post

parameter

WithContext method only

UpdateVisibilityOptions

The UpdateVisibility options.

UpdateVisibilityOptions

The updateVisibility options.

parameters

id
Required*
string
The object's unique ID.
extendable
boolean
Allows the visibility to be extenable.
include
Visibility details related to a catalog entry.
exclude
Visibility details related to a catalog entry.
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

id
Required*
str
The object's unique ID.
extendable
bool
Allows the visibility to be extenable.
include
Visibility details related to a catalog entry.
exclude
Visibility details related to a catalog entry.
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.

Example request

curl --request PUT --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/visibility?account=string' --header 'accept: application/json'
--data '{"approved":true,"exclude":{"properties":{"accounts":{"properties":{"_accountid_":"string"},"type":"object"}},"required":["accounts"],"type":"object"},"include":{"properties":{"accounts":{"properties":{"_accountid_":"string"},"type":"object"}},"required":["accounts"],"type":"object"},"owner":{"properties":{"type":"string","value":"string"},"type":"object"},"restrictions":"string"}'

Example request

updateVisibilityOptions := globalCatalogService.NewUpdateVisibilityOptions(
  catalogEntryID,
)
updateVisibilityOptions.SetExtendable(false)

response, err := globalCatalogService.UpdateVisibility(updateVisibilityOptions)
if err != nil {
  fmt.Println("UpdateVisibility() returned the following error: ", err.Error())
}

Example request

UpdateVisibilityOptions updateVisibilityOptions = new UpdateVisibilityOptions.Builder()
    .id(catalogEntryId)
    .extendable(false)
    .build();

service.updateVisibility(updateVisibilityOptions).execute();

Example request

const params = {
  id: catalogEntryId,
  extendable: false,
};

globalCatalogService.updateVisibility(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.log('updateVisibility() returned the following error: ' + err);
  });

Example request

response = global_catalog_service.update_visibility(
  id=catalog_entry_id,
  extendable=False,
).get_result()

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

Response

Status Code

200
Successfully updated the visibility of the catalog entry.
401
Unauthorized
403
Permission Denied: You must have an Adminstrator role to set visibility of a catalog entry.
404
Object was not found.

No Sample Response

This method does not specify any sample responses.

This endpoint returns the pricing for an object. Static pricing is defined in the catalog. Dynamic pricing is stored in IBM Cloud Pricing Catalog. This can be used by an unauthenticated user for publicly available services.

GET /{id}/pricing

(globalCatalog *GlobalCatalogV1) GetPricing(getPricingOptions *GetPricingOptions) (result *PricingGet, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetPricingWithContext(ctx context.Context, getPricingOptions *GetPricingOptions) (result *PricingGet, response *core.DetailedResponse, err error)

ServiceCall<PricingGet> getPricing(GetPricingOptions getPricingOptions)

getPricing(params)

get_pricing(self,
        id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetPricingOptions struct and set the fields to provide parameter values for the GetPricing method.

Use the GetPricingOptions.Builder to create a GetPricingOptions object that contains the parameter values for the getPricing method.

Path Parameters

id
Required*
string
The object's unique ID

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.

parameter

WithContext method only

GetPricingOptions

The GetPricing options.

GetPricingOptions

The getPricing options.

parameters

id
Required*
string
The object's unique ID.
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

id
Required*
str
The object's unique ID.
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.

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/pricing?account=string' --header 'accept: application/json'

Example request

getPricingOptions := globalCatalogService.NewGetPricingOptions(
  catalogEntryID,
)

pricingGet, response, err := globalCatalogService.GetPricing(getPricingOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(pricingGet, "", "  ")
fmt.Println(string(b))

Example request

GetPricingOptions getPricingOptions = new GetPricingOptions.Builder()
    .id(catalogEntryId).build();

Response<PricingGet> response = service.getPricing(getPricingOptions).execute();
PricingGet pricingGet = response.getResult();

System.out.println(pricingGet);

Example request

const params = {
  id: catalogEntryId,
};

globalCatalogService.getPricing(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

pricing_get = global_catalog_service.get_pricing(
  id=catalog_entry_id,
).get_result()

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

Response

Response Body

PricingGet

Pricing-related information

PricingGet

Pricing-related information.

PricingGet

Pricing-related information.

PricingGet

Pricing-related information.

PricingGet

Pricing-related information.

Status Code

200
The pricing for the object
401
Unauthorized
403
No Permissions
404
Pricing not available

Example responses

Status 200

{
  "deployment_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d:global",
  "deployment_location": "global",
  "origin": "pricing_catalog",
  "type": "paygo",
  "i18n": {},
  "starting_price": {},
  "effective_from": "2021-01-01T00:00:00Z",
  "effective_until": "9999-12-30T16:00:00Z",
  "metrics": [
    {
      "part_ref": "",
      "metric_id": "COSVLTSTOR",
      "tier_model": "Step Tier",
      "resource_display_name": "Vault storage",
      "charge_unit_display_name": "GIGABYTE",
      "charge_unit_name": "VAULT_STORAGE",
      "charge_unit": "GIGABYTE",
      "charge_unit_quantity": 1,
      "amounts": [
        {
          "country": "USA",
          "currency": "USD",
          "prices": [
            {
              "quantity_tier": 499999,
              "price": 0.02
            },
            {
              "quantity_tier": 999999999,
              "price": 0.018
            }
          ]
        }
      ]
    }
  ]
}

Success example

{
  "deployment_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d:global",
  "deployment_location": "global",
  "origin": "pricing_catalog",
  "type": "paygo",
  "i18n": {},
  "starting_price": {},
  "effective_from": "2021-01-01T00:00:00Z",
  "effective_until": "9999-12-30T16:00:00Z",
  "metrics": [
    {
      "part_ref": "",
      "metric_id": "COSVLTSTOR",
      "tier_model": "Step Tier",
      "resource_display_name": "Vault storage",
      "charge_unit_display_name": "GIGABYTE",
      "charge_unit_name": "VAULT_STORAGE",
      "charge_unit": "GIGABYTE",
      "charge_unit_quantity": 1,
      "amounts": [
        {
          "country": "USA",
          "currency": "USD",
          "prices": [
            {
              "quantity_tier": 499999,
              "price": 0.02
            },
            {
              "quantity_tier": 999999999,
              "price": 0.018
            }
          ]
        }
      ]
    }
  ]
}

This endpoint returns the deployment pricing for a plan. For a plan it returns a pricing for each visible child deployment object. Static pricing is defined in the catalog. Dynamic pricing is stored in IBM Cloud Pricing Catalog. This can be used by an unauthenticated user for publicly available services.

GET /{id}/pricing/deployment

Request

Path Parameters

id
Required*
string
The object's unique ID

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.

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/pricing?account=string' --header 'accept: application/json'

Response

Response Body

PricingSearchResult

A paginated result containing pricing entries.

Status Code

200
The pricing for the object
401
Unauthorized
403
No Permissions
404
Pricing not available

Example responses

Status 200

{
  "offset": 0,
  "limit": 50,
  "count": 1,
  "resource_count": 1,
  "resources": [
    {
      "deployment_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d:global",
      "deployment_location": "global",
      "origin": "pricing_catalog",
      "type": "paygo",
      "i18n": {},
      "starting_price": {},
      "effective_from": "2021-01-01T00:00:00Z",
      "effective_until": "9999-12-30T16:00:00Z",
      "metrics": [
        {
          "part_ref": "",
          "metric_id": "COSVLTSTOR",
          "tier_model": "Step Tier",
          "resource_display_name": "Vault storage",
          "charge_unit_display_name": "GIGABYTE",
          "charge_unit_name": "VAULT_STORAGE",
          "charge_unit": "GIGABYTE",
          "charge_unit_quantity": 1,
          "amounts": [
            {
              "country": "USA",
              "currency": "USD",
              "prices": [
                {
                  "quantity_tier": 499999,
                  "price": 0.02
                },
                {
                  "quantity_tier": 999999999,
                  "price": 0.018
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

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

GET /{id}/logs

(globalCatalog *GlobalCatalogV1) GetAuditLogs(getAuditLogsOptions *GetAuditLogsOptions) (result *AuditSearchResult, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetAuditLogsWithContext(ctx context.Context, getAuditLogsOptions *GetAuditLogsOptions) (result *AuditSearchResult, response *core.DetailedResponse, err error)

ServiceCall<AuditSearchResult> getAuditLogs(GetAuditLogsOptions getAuditLogsOptions)

getAuditLogs(params)

get_audit_logs(self,
        id: str,
        *,
        account: str = None,
        ascending: str = None,
        startat: str = None,
        offset: int = None,
        limit: int = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetAuditLogsOptions struct and set the fields to provide parameter values for the GetAuditLogs method.

Use the GetAuditLogsOptions.Builder to create a GetAuditLogsOptions object that contains the parameter values for the getAuditLogs method.

Path Parameters

id
Required*
string
The object's unique ID

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.
ascending
string
Sets the sort order. False is descending.

Default: false
startat
string
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
_offset
integer
Count of number of log entries to skip before returning logs. The default is zero.

Default: 0
_limit
integer
Count of number of entries to return. The default is fifty. The maximum value is two hundred.

Possible values: value ≤ 200
Default: 50

parameter

WithContext method only

GetAuditLogsOptions

The GetAuditLogs options.

GetAuditLogsOptions

The getAuditLogs options.

parameters

id
Required*
string
The object's unique ID.
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.
ascending
string
Sets the sort order. False is descending.

Default: false
startat
string
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.
offset
number
Count of number of log entries to skip before returning logs. The default is zero.
limit
number
Count of number of entries to return. The default is fifty. The maximum value is two hundred.

Possible values: value ≤ 200

parameters

id
Required*
str
The object's unique ID.
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.
ascending
str
Sets the sort order. False is descending.

Default: false
startat
str
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.
offset
int
Count of number of log entries to skip before returning logs. The default is zero.
limit
int
Count of number of entries to return. The default is fifty. The maximum value is two hundred.

Possible values: value ≤ 200

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{id}/logs?account=string&ascending=false&startat=string&_offset=0&_limit=50' --header 'accept: application/json'

Example request

getAuditLogsOptions := globalCatalogService.NewGetAuditLogsOptions(
  catalogEntryID,
)
getAuditLogsOptions.SetOffset(0)
getAuditLogsOptions.SetLimit(10)

auditSearchResult, response, err := globalCatalogService.GetAuditLogs(getAuditLogsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(auditSearchResult, "", "  ")
fmt.Println(string(b))

Example request

GetAuditLogsOptions getAuditLogsOptions = new GetAuditLogsOptions.Builder()
    .id(catalogEntryId)
    .offset(0)
    .limit(10)
    .build();

Response<AuditSearchResult> response = service.getAuditLogs(getAuditLogsOptions).execute();
AuditSearchResult auditSearchResult = response.getResult();

System.out.println(auditSearchResult);

Example request

const params = {
  id: catalogEntryId,
  offset: 0,
  limit: 10,
};

globalCatalogService.getAuditLogs(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

audit_search_result = global_catalog_service.get_audit_logs(
  id=catalog_entry_id,
  offset=0,
  limit=10,
).get_result()

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

Response

Response Body

AuditSearchResult

A paginated search result containing audit logs.

AuditSearchResult

A paginated search result containing audit logs.

AuditSearchResult

A paginated search result containing audit logs.

AuditSearchResult

A paginated search result containing audit logs.

AuditSearchResult

A paginated search result containing audit logs.

Status Code

200
The audit logs for the object
401
Unauthorized
403
No Permissions
404
Object not found or is archived

Example responses

Status 200

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

Success example

{
  "page": "STRING",
  "resources": "ARRAY",
  "results_per_page": "STRING",
  "total_results": "STRING"
}

This endpoint returns a list of artifacts for an object.

GET /{object_id}/artifacts

(globalCatalog *GlobalCatalogV1) ListArtifacts(listArtifactsOptions *ListArtifactsOptions) (result *Artifacts, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) ListArtifactsWithContext(ctx context.Context, listArtifactsOptions *ListArtifactsOptions) (result *Artifacts, response *core.DetailedResponse, err error)

ServiceCall<Artifacts> listArtifacts(ListArtifactsOptions listArtifactsOptions)

listArtifacts(params)

list_artifacts(self,
        object_id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the ListArtifactsOptions struct and set the fields to provide parameter values for the ListArtifacts method.

Use the ListArtifactsOptions.Builder to create a ListArtifactsOptions object that contains the parameter values for the listArtifacts method.

Path Parameters

object_id
Required*
string
The object's unique ID

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.

parameter

WithContext method only

ListArtifactsOptions

The ListArtifacts options.

ListArtifactsOptions

The listArtifacts options.

parameters

objectId
Required*
string
The object's unique ID.
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

object_id
Required*
str
The object's unique ID.
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.

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{object_id}/artifacts?account=string' --header 'accept: application/json'

Example request

listArtifactsOptions := globalCatalogService.NewListArtifactsOptions(
  catalogEntryID,
)

artifacts, response, err := globalCatalogService.ListArtifacts(listArtifactsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(artifacts, "", "  ")
fmt.Println(string(b))

Example request

ListArtifactsOptions listArtifactsOptions = new ListArtifactsOptions.Builder()
    .objectId(catalogEntryId)
    .build();

Response<Artifacts> response = service.listArtifacts(listArtifactsOptions).execute();
Artifacts artifacts = response.getResult();

System.out.println(artifacts);

Example request

const params = {
  objectId: catalogEntryId,
};

globalCatalogService.listArtifacts(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

artifacts = global_catalog_service.list_artifacts(
  object_id=catalog_entry_id).get_result()

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

Response

Response Body

Artifacts

Artifacts List

Artifacts

Artifacts List.

Artifacts

Artifacts List.

Artifacts

Artifacts List.

Artifacts

Artifacts List.

Status Code

200
The artifacts for the object
401
Unauthorized
403
No Permissions
404
Artifact not found

Example responses

Status 200

{
  "count": "INTEGER",
  "resources": {
    "etag": "STRING",
    "name": "STRING",
    "size": "INTEGER",
    "updated": "STRING",
    "url": "STRING"
  }
}

Success example

{
  "count": "INTEGER",
  "resources": {
    "etag": "STRING",
    "name": "STRING",
    "size": "INTEGER",
    "updated": "STRING",
    "url": "STRING"
  }
}

This endpoint returns the binary of an artifact.

GET /{object_id}/artifacts/{artifact_id}

(globalCatalog *GlobalCatalogV1) GetArtifact(getArtifactOptions *GetArtifactOptions) (result io.ReadCloser, response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) GetArtifactWithContext(ctx context.Context, getArtifactOptions *GetArtifactOptions) (result io.ReadCloser, response *core.DetailedResponse, err error)

ServiceCall<InputStream> getArtifact(GetArtifactOptions getArtifactOptions)

getArtifact(params)

get_artifact(self,
        object_id: str,
        artifact_id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the GetArtifactOptions struct and set the fields to provide parameter values for the GetArtifact method.

Use the GetArtifactOptions.Builder to create a GetArtifactOptions object that contains the parameter values for the getArtifact method.

Path Parameters

object_id
Required*
string
The object's unique ID
artifact_id
Required*
string
The artifact's ID

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.

parameter

WithContext method only

GetArtifactOptions

The GetArtifact options.

GetArtifactOptions

The getArtifact options.

parameters

objectId
Required*
string
The object's unique ID.
artifactId
Required*
string
The artifact's ID.
accept
string
The type of the response: or /.
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

object_id
Required*
str
The object's unique ID.
artifact_id
Required*
str
The artifact's ID.
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.

Example request

curl --request GET --url 'https://globalcatalog.cloud.ibm.com/api/v1/{object_id}/artifacts/{artifact_id}?account=string' --header 'accept: application/json'

Example request

getArtifactOptions := globalCatalogService.NewGetArtifactOptions(
  catalogEntryID,
  "artifact.txt",
)

result, response, err := globalCatalogService.GetArtifact(getArtifactOptions)
if err != nil {
  panic(err)
}
if result != nil {
  defer result.Close()
  buf := new(bytes.Buffer)
  buf.ReadFrom(result)
  fmt.Println("Artifact content-type: ", response.GetHeaders().Get("Content-Type"))
  fmt.Println("Artifact contents: ", buf.String())
}

Example request

GetArtifactOptions getArtifactOptions = new GetArtifactOptions.Builder()
    .objectId(catalogEntryId)
    .artifactId("artifact.txt")
    .build();

Response<InputStream> response = service.getArtifact(getArtifactOptions).execute();
InputStream inputStream = response.getResult();
if (inputStream != null) {
  String artifactContents = IOUtils.toString(inputStream, StandardCharsets.UTF_8);
  inputStream.close();
  System.out.println("Artifact content-type: " + response.getHeaders().values("Content-Type"));
  System.out.println("Artifact contents: " + artifactContents);
}

Example request

const params = {
  objectId: catalogEntryId,
  artifactId: 'artifact.txt',
};

globalCatalogService.getArtifact(params)
  .then(res => {
    responseContentType = res.headers['content-type'];
    return streamToPromise(res.result);
  })
  .then(contents => {
    console.log(`Artifact content type: {responseContentType}\nArtifact contents: {contents}`);
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = global_catalog_service.get_artifact(
  object_id=catalog_entry_id,
  artifact_id='artifact.txt',
)

content_type = response.get_headers().get('content-type')
result = response.get_result()
print('Artifact content-type: {0}'.format(content_type))
print('Artifact contents: {0}'.format(str(result.content)))

Response

Response type: io.ReadCloser

Response type: InputStream

Response type: NodeJS.ReadableStream|Buffer

Response type: BinaryIO

Response Body

binary

Status Code

200
The contents of the artifact. The Content-Type header returned in the response indicates the mime-type associated with the artifact.
304
If using header 'If-None-Match' with an ETag this will be returned if the ETag matches.
401
Unauthorized
403
No Permissions
404
Artifact not found

No Sample Response

This method does not specify any sample responses.

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

PUT /{object_id}/artifacts/{artifact_id}

(globalCatalog *GlobalCatalogV1) UploadArtifact(uploadArtifactOptions *UploadArtifactOptions) (response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) UploadArtifactWithContext(ctx context.Context, uploadArtifactOptions *UploadArtifactOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> uploadArtifact(UploadArtifactOptions uploadArtifactOptions)

uploadArtifact(params)

upload_artifact(self,
        object_id: str,
        artifact_id: str,
        *,
        artifact: BinaryIO = None,
        content_type: str = None,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the UploadArtifactOptions struct and set the fields to provide parameter values for the UploadArtifact method.

Use the UploadArtifactOptions.Builder to create a UploadArtifactOptions object that contains the parameter values for the uploadArtifact method.

Path Parameters

object_id
Required*
string
The object's unique ID
artifact_id
Required*
string
The artifact's ID

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

*/*binary

parameter

WithContext method only

UploadArtifactOptions

The UploadArtifact options.

UploadArtifactOptions

The uploadArtifact options.

parameters

objectId
Required*
string
The object's unique ID.
artifactId
Required*
string
The artifact's ID.
artifact
NodeJS.ReadableStream
contentType
string
The type of the input.
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

object_id
Required*
str
The object's unique ID.
artifact_id
Required*
str
The artifact's ID.
artifact
BinaryIO
content_type
str
The type of the input.
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.

Example request

curl --request PUT --url 'https://globalcatalog.cloud.ibm.com/api/v1/{object_id}/artifacts/{artifact_id}?account=string' --header 'accept: application/json'

Example request

artifactContents := "This is an example artifact associated with a catalog entry."

uploadArtifactOptions := globalCatalogService.NewUploadArtifactOptions(
  catalogEntryID,
  "artifact.txt",
)
uploadArtifactOptions.SetArtifact(ioutil.NopCloser(strings.NewReader(artifactContents)))
uploadArtifactOptions.SetContentType("text/plain")

response, err := globalCatalogService.UploadArtifact(uploadArtifactOptions)
if err != nil {
  panic(err)
}

Example request

String artifactContents = "This is an example artifact associated with a catalog entry.";

UploadArtifactOptions uploadArtifactOptions = new UploadArtifactOptions.Builder()
    .objectId(catalogEntryId)
    .artifactId("artifact.txt")
    .artifact(new ByteArrayInputStream(artifactContents.getBytes(StandardCharsets.UTF_8)))
    .contentType("text/plain")
    .build();

service.uploadArtifact(uploadArtifactOptions).execute();

Example request

const params = {
  objectId: catalogEntryId,
  artifactId: 'artifact.txt',
  artifact: Buffer.from('This is an example artifact associated with a catalog entry.', 'utf8'),
  contentType: 'text/plain',
};

globalCatalogService.uploadArtifact(params)
  .then(res => {
    console.log(JSON.stringify(res, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

artifact_contents = io.BytesIO(
  b'This is an example artifact associated with a catalog entry.')

response = global_catalog_service.upload_artifact(
  object_id=catalog_entry_id,
  artifact_id='artifact.txt',
  artifact=artifact_contents,
  content_type='text/plain',
).get_result()

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

Response

Status Code

200
Successfully uploaded the artifact

No Sample Response

This method does not specify any sample responses.

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

DELETE /{object_id}/artifacts/{artifact_id}

(globalCatalog *GlobalCatalogV1) DeleteArtifact(deleteArtifactOptions *DeleteArtifactOptions) (response *core.DetailedResponse, err error)

(globalCatalog *GlobalCatalogV1) DeleteArtifactWithContext(ctx context.Context, deleteArtifactOptions *DeleteArtifactOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteArtifact(DeleteArtifactOptions deleteArtifactOptions)

deleteArtifact(params)

delete_artifact(self,
        object_id: str,
        artifact_id: str,
        *,
        account: str = None,
        **kwargs
    ) -> DetailedResponse

Request

Instantiate the DeleteArtifactOptions struct and set the fields to provide parameter values for the DeleteArtifact method.

Use the DeleteArtifactOptions.Builder to create a DeleteArtifactOptions object that contains the parameter values for the deleteArtifact method.

Path Parameters

object_id
Required*
string
The object's unique ID
artifact_id
Required*
string
The artifact's ID

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.

parameter

WithContext method only

DeleteArtifactOptions

The DeleteArtifact options.

DeleteArtifactOptions

The deleteArtifact options.

parameters

objectId
Required*
string
The object's unique ID.
artifactId
Required*
string
The artifact's ID.
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

object_id
Required*
str
The object's unique ID.
artifact_id
Required*
str
The artifact's ID.
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.

Example request

curl --request DELETE --url 'https://globalcatalog.cloud.ibm.com/api/v1/{object_id}/artifacts/{artifact_id}?account=string' --header 'accept: application/json'

Example request

deleteArtifactOptions := globalCatalogService.NewDeleteArtifactOptions(
  catalogEntryID,
  "artifact.txt",
)

response, err := globalCatalogService.DeleteArtifact(deleteArtifactOptions)
if err != nil {
  panic(err)
}

Example request

DeleteArtifactOptions deleteArtifactOptions = new DeleteArtifactOptions.Builder()
    .objectId(catalogEntryId)
    .artifactId("artifact.txt")
    .build();

service.deleteArtifact(deleteArtifactOptions).execute();

Example request

const params = {
  objectId: catalogEntryId,
  artifactId: 'artifact.txt',
};

globalCatalogService.deleteArtifact(params)
  .then(res => {
    console.log(JSON.stringify(res, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = global_catalog_service.delete_artifact(
  object_id=catalog_entry_id,
  artifact_id='artifact.txt',
).get_result()

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

Introduction

Endpoint URLs

Authentication

Error handling

Event tracking

Related APIs

Methods

Returns parent catalog entries

Request

Query Parameters

account

include

q

sort-by

descending

languages

catalog

complete

_offset

_limit

parameter

ctx

ListCatalogEntriesOptions

Account

Include

Q

SortBy

Descending

Languages

Catalog

Complete

Offset

Limit

ListCatalogEntriesOptions

account

include

q

sortBy

descending

languages

catalog

complete

offset

limit

parameters

account

include

q

sortBy

descending

languages

catalog

complete

offset

limit

parameters

account

include

q

sort_by

descending

languages

catalog

complete

offset

limit

Response

Response Body

offset

limit

count

resource_count

first

last

prev

next

resources

EntrySearchResult

Offset

Limit