vRealize Automation Catalog Service API 7.5

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

Related Sample Code

  • vRealize Automation - Catalog Service

    Contributor VMware

    vRealize Automation - Catalog Service 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 ...
    api_vra_catalog vRealize Automation api_vra_composition POSTMAN Collection
    Download

    1 Favorite

    0 Comments

    Updated 1 year ago

  • Submit a catalog item request via vRA API in PowerShell

    Contributor tnavarro1

    Submits a catalog item request via the vRA API in PowerShell
    vRealize Automation PowerShell
    Download

    2 Comments

    Updated 4 months ago

  • Submit a day-2 or resource action request via vRA API in PowerShell

    Contributor tnavarro1

    Submit a day-2 or resource action request via vRA API in PowerShell
    vRealize Automation PowerShell
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation API Samples for Postman

    Contributor nsb24

    vRealize Automation API Samples for Postman Overview The vRealize Automation REST API provides consumers and administrators access to all services in its service catalog that support the vRealize Auto ...
    vRealize Automation POSTMAN Collection
    Download

    1 Favorite

    0 Comments

    Updated 6 months ago

  • vRealize Automation - NSX Integration

    Contributor VMware

    vRealize Automation - NSX Integration NSX integration in vRealize Automation can help creating and configuring existing networks, on-demand NAT networks and on-demand routed networks, creating load ba ...
    vRealize Automation api_vra_network POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • VMware vRealize Automation Plugin

    Contributor kr1s

    Jenkins vRealize Automation Plugin The vRealize Automation Jenkins plugin enables Jenkins to provision vRealize Automation 7 Blueprints. Requirements Jenkins 1.58+ Java 8 to compile plugin or Java 7 ...
    vRealize Automation Java
    Download

    3 Favorites

    1 Comment

    Updated 2 months ago

  • vRealize Automation - Composition Service

    Contributor VMware

    vRealize Automation - Composition Service The composition service allows vRA services to register application components, which the composition service manages so that they can be used in composite bl ...
    vRealize Automation api_vra_composition POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Identity Service

    Contributor VMware

    vRealize Automation - Identity Service Identity service manages tenants, business groups (formerly named subtenants), groups (both Single-Sign-On and Custom groups), users and identity stores. It also ...
    vRealize Automation api_vra_identity POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Content Management Service

    Contributor VMware

    vRealize Automation - Content Management Service You can use the content management service REST API to import and export content, such as blueprints, software components, and other artifacts, from vR ...
    vRealize Automation api_vra_content_management api_vra_composition POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Component Registry

    Contributor VMware

    vRealize Automation - Component Registry Component Registry manages all services (including out-of-the-box services and services from third party solution providers) and serves as the central view for ...
    api_vra_component_registry vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Event Broker

    Contributor VMware

    vRealize Automation - Event Broker The event broker provides features for managing subscriptions, event topics, events, and messages. Available Use Case Get event topics Registers or updates an Even ...
    vRealize Automation api_vra_event_broker POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Branding

    Contributor VMware

    vRealize Automation - Branding The Branding service enables the user to customize the VRA UI header and footer. The configurable properties include logo image, company name, product name, background c ...
    api_vra_branding vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Management Service API

    Contributor VMware

    vRealize Automation - Management Service API You can use the reclamation service to query the VMs in an installation for non-usage and, if they are not in use, mark them as eligible for reclamation. ...
    vRealize Automation api_vra_management POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Properties Service

    Contributor VMware

    vRealize Automation - Properties Service The property service provides APIs to manage property definitions and property groups. Available Use Cases Manage property definitions Manage property groups ...
    api_vra_properties vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - Approval Service

    Contributor VMware

    vRealize Automation - Approval Service The approval service provides features for managing and tracking the human approval tasks associated with a service process/artifact in a provider realm. It also ...
    api_vra_approval vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation - WorkItem Service

    Contributor VMware

    vRealize Automation - WorkItem Service The work item service provides a standard way for services to present work items to users. It manages the life-cycle of a work item and passes events back to the ...
    api_vra_approval api_vra_workitem vRealize Automation POSTMAN Collection
    Download

    0 Comments

    Updated 1 year ago

  • vRealize Automation Reference Application

    Contributor hmichaud

    vRealize Automation Reference Application Overview This is a sample project that demonstrates how to create a simple self-service portal for vRealize Automation using only RESTful APIs. You are encour ...
    vRealize Automation JavaScript
    Download

    2 Favorites

    4 Comments

    Updated 1 year ago

  • Project Bosphorus

    Contributor prydin

    Project Bosphorus Background This project is aimed at providing a custom portal framework for vRealize Automation (vRA) along with a reference implementation. It is intended for advanced users/develop ...
    vRealize Automation Java
    Download

    1 Comment

    Updated 1 year ago

  • vRA and Ansible Example Integration

    Contributor vm2cloud

    vRealize Automation vRO Package
    Download

    0 Comments

    Updated 2 years ago

  • vRA 7 and above prepare_vra_template.ps1

    Contributor virtualgcoburn

    Powershell script designed to deploy the needed agents on your windows template. This mimics the prepare_vra_template.sh file for linux and will deploy java, bootstrap and gugent agents from the vRA a ...
    vRealize Automation PowerShell
    Download

    1 Comment

    Updated 1 year ago