vRealize Automation Catalog Service API

Catalog Service API Specification

What is the Catalog Service REST API?

The catalog service REST API is designed to be used by the consumers of the service catalog; for example, an end user who wants to request a catalog item would be a consumer of this API. The catalog service imposes a maximum limit on the number of elements that can be retrieved with a single API call. This limit is currently set to 5000.

How the Catalog Service Works

The Catalog Service REST API comprises three APIs:

  • Catalog Consumer REST API - When end users request catalog items, the catalog consumer REST API is called.
  • Catalog Service Provider API - Service providers use the catalog Service Provider API to design and publish catalog items and fulfill requests for them.
  • Catalog Service Admin API - When system administrators interact with catalog items, the catalog Service Admin API is called.

Key Concepts

Catalog Item

An item that is listed in a service catalog. Some catalog items result in an item being provisioned that the user can manage through its life cycle. For example, an application developer can request storage as a service, then later add capacity, request backups, and restore previous backups.

Other catalog items do not result in provisioned items. For example, a cell phone user can submit a request for additional minutes on a mobile plan.

Catalog Consumer

An end user of a service. Consumers can request catalog items from the service catalog.

Catalog Service Provider

A service provider who designs, publishes, and fulfills requests for catalog items provided to catalog consumers.

Using the Catalog Consumer API

The catalog consumer REST API is designed to be used by the consumers of the service catalog; for example, an end user who wants to request a catalog item would be a consumer of this API.

Base URI : /api/consumer
Resource Resource URI Notes
Catalog Items /catalogItems
 Consumer REST API for catalog items. This API does not take entitlements into account but only global user permissions.
However, if a request is submitted for a catalog item without the appropriate entitlement, it will be rejected.
Entitled Catalog Items  /entitledCatalogItems
 Consumer REST API for entitled catalog items exposed for users. Consumer entitled catalogItem(s) are basically catalog items that:
- are in an active state.
- the current user has the right to consume.
- the current user is entitled to consume.
- are associated to a service.
Requests /requests
 Consumer request API exposed to users. The request captures the user's input (done through a form) and triggers the process that fulfills that order on the appropriate provider.
Resources /resources
 Consumer resource API exposed to users. A Resource represents a deployed artifact that has been provisioned by a provider.
Resource Operations /resourceOperations
 Consumer resource operation API exposed to users. A resource operation represents a Day-2 operation that can be performed on a resource. Resource operations are registered in the Service Catalog and target a specific resource type. These operations can be invoked / accessed by consumers through the self-service interface on the resources they own.
Resource Types /resourceTypes
 Consumer resource type API exposed to users. Resource types is a type assigned to resources. The types are defined by the provider types. It allows similar resources to be grouped together.
Services /services
 Consumer service API exposed to users. A service represents a customer-facing/user friendly set of activities. In the context of this service catalog, these activities are the catalog item. A service must be owned by a specific organization (tenant and subtenant, i.e., business group), and all the activities it contains should belong to the same organization.

Using the Catalog Service Provider API

The catalog service provider API is designed for use by service providers who want their services to be consumed by the vRA catalog. A service catalog provider is responsible for:

  • The design and the maintenance of the catalog items in its own UI.
  • The publication of the catalog items to the service catalog.
  • The fulfillment of the catalog items request.
Base URI : /api/provider
Resource Resource URI Notes
Catalog Items /providers/{providerId}/catalogItems
 Provider REST API for provider catalog items. Provider catalog item represents the catalog item object submitted by a provider. This object is very similar to the catalog item entity. The only noticeable difference is that the ID field does not represent the entity ID but the external ID used by the provider. (This ID is stored as a `bindingId` field in the catalog item entity because it may not be unique in the service catalog context).
Catalog Item Types /catalogItemTypes
 Provider REST API for catalog items exposed for users. Catalog item types define various common properties shared by catalog items (such as the output). They also enable presentation and comparison of similar catalog items for the consumer. Catalog item types can also define the tracked resource produced (such as a deployed VM) if any.
Requests /providers/{providerId}/requests
 Provider Request API exposed to users. The request captures the user's input (done through a form) and trigger the process that fulfils that order on the appropriate provider.
Resources /providers/{providerId}/resources
 Provider resource API exposed to users. A Resource represents a deployed artifact that has been provisioned by a provider.
Resource Actions /resourceActions
 Provider Resource Action API exposed to users. A resource action represents a Day-2 operation that can be performed on a resource. Resource actions are registered in the service catalog and target a specific resource type. These operations can be invoked / accessed by consumers through the self-service interface on the resources they own. Resource actions must be unique based on the combo of binding id and provider type/ provider. When a new resource action is registered without a catalog-assigned id, the catalog will attempt to match that action to an existing record with the same provider-binding. If successful, the existing resource action is updated. If not, the resource action is registered as a new record.
Resource Types /resourceTypes
 Provider resource type API exposed to users. Resource types is a type assigned to resources. The types are defined by the provider types. It allows similar resources to be grouped together.
Icons /icons
 Provider REST API exposed to users for to publish icons to the service catalog.. It represents an icon with all its descriptive meta data (fileName, MIME Type...). The actual content of the icon is stored as a byte[]. Icons can be solution-level or belong to a specific tenant. Solution-level icons are created through the provider API, and the fileName will be the same as the ID for these icons. Organization will be null in this case. Organization-specific icons are uploaded through the admin API. For these icons, the fileName will be specified, but the ID will be generated. Oganization will be set (Tenant mandatory, team optional).

Using the Catalog Admin API

The catalog admin API is an API for catalog items that a system administrator can interact with. It allows the user to interact with catalog items that the user is permitted to review, even if the items were not published or the user is not entitled to them.

Base URI : /api
Resource Resource URI Notes
Catalog Items /catalogItems
 REST API for catalog items that a system administrator can interact with. It allows the user to interact with catalog items that the user is permitted to review, even if they were not published or entitled to them.
Entitled Catalog Items  /entitledCatalogItems
 REST API for administrators to interact with catalog items that they are entitled to. Consumer-entitled catalog item(s) are basically catalog items that:
- are in an active state.
- the current user has the right to consume.
- the current user is entitled to consume.
- are associated to a service.
Requests /requests
 Request API exposed to administrators. The request captures the user's input (done through a form) and trigger the process that fulfills that order on the appropriate provider.
Resources /resources
 Resource API exposed to administrators. A resource represents a deployed artifact that has been provisioned by a provider.
Resource Operations /resourceOperations
 Resource operation API exposed to administrators. A resource operation represents a Day-2 operation that can be performed on a resource. Resource operations are registered in the service catalog and target a specific resource type. These operations can be invoked / accessed by consumers through the self-service interface on the resources they own.
Resource Types /resourceTypes
 Resource type API exposed to administrators. Resource types is a type assigned to resources. The types are defined by the provider types. It allows similar resources to be grouped together.
Services /services
 Service API exposed to administrators. A service represents a customer-facing/user friendly set of activities. In the context of this service catalog, these activities are the catalog items and resource actions. A service must be owned by a specific organization (tenant and subtenant, i.e., business group), and all the activities it contains should belong to the same organization.
Icons /icons
 Icons API exposed to administrators. Icons can be published to the catalog.
Usage Examples

Getting a list of catalog items:

 GET /consumer/catalogItems

Getting a catalog item by id:

 GET consumer/catalogItems/0581d671-93fd-4bca-aa05-2e14514c4ef9>

Important Notes About catalog-service and OData Queries

catalog-service behaves differently than other vRA services when it comes to OData queries. Before proceeding, please familiarize yourself with the generic use case of how to use OData in the vRA REST API.

Some catalog-service domain models contain nested objects ending in 'Ref' (which denotes the nested object is a reference to an object rather than a full-blown nested object). When crafting your $filter query, you must remove 'Ref'. Also, each 'Ref' object contains an id and sometimes a label. When attempting to filter on these fields, you must use OData resources of id and name (respectively).

Here's an example to make things clearer. Let's say you want to see all consumer catalog items that are associated with a specific catalog service name. As mentioned in the walkthrough, you'll want to look at the catalogItem domain object (which is linked from the CatalogItem REST Resource documentation page).

The catalogItem domain object contains a serviceRef, which itself has a id and label. If we want to filter based on a service name, we would use a 'curl' command like this:

 curl -H "Accept: $ACCEPT" -H "Authorization: $AUTH"
 "https://$VRA/catalog-service/api/consumer/catalogItems?%24filter=service/name+eq+'some-service'"

Note: Notice how even though the serviceRef object contains a label element, we use service (and not serviceRef) and name (and not label) to craft the filter: $filter=service/name eq 'theName'

Follow this pattern when crafting any OData queries against >catalog-service when you encounter domain objects containing 'Ref'. Also, look at the REST resource API documentation, which may give more details on supported OData queries.

 

Related Documentation

Name Size
Swagger/Open API specification download
vRealize Automation Programming Guide 2.1 MB

Related Sample Code