Manage Catalog Items and Folders Using REST APIs

You can use Oracle Analytics Cloud REST APIs to programmatically list artifacts stored in the catalog, create and delete folders, copy and move catalog items, change ownership of catalog items, and update catalog item access control lists (ACL).

Here are some common tasks using REST APIs.

Task Description REST API Documentation
Understand prerequisites

Understand and complete several prerequisite tasks.

You must the DV Content Author application role to use catalog REST APIs, except for operations that use manageContent which require you to have the BI Service Administrator application role or an application role with the Manage Content permission.

Prerequisites
Understand OAuth 2.0 token authentication Authentication and authorization in Oracle Analytics Cloud is managed by Oracle Identity Cloud Service. To access the Oracle Analytics Cloud REST APIs, you need an OAuth 2.0 access token to use for authorization. OAuth 2.0 Token Authentication
Get catalog artifacts Get details for a single item, items by type, items that match search criteria, item ACL details. Get catalog item details

Get catalog items

Get catalog items by type

Get catalog item ACL
Create and delete folders Create and delete folders that store catalog items.

Create a folder

Delete a folder
Move and copy catalog items Move (or copy) catalog items with a given type and ID to a specific folder.

Copy a catalog item

Move a catalog item
Update access control details Update the access control list (ACL) for a catalog item with a given ID.

Update a catalog item ACL
Change catalog item ownership Change the ownership of catalog item. You need the Manage Content permission to change the ownership of objects.

Change item ownership

About Catalog REST APIs 503 Service Unavailable Responses

Catalog REST APIs use the catalog search index to list and search for catalog objects. The REST API returns matching search results only when the search index is built and ready to use.

If a Catalog API request returns no results, the API performs a search index readiness check. If the Catalog API detects that a search index build is in progress, the API returns 503 Service Unavailable with a Retry-After header instead of an empty result set.

A503 Service Unavailable response with SearchIndexNotReady indicates a temporary condition. Retry the request after the delay specified in the Retry-After header.

For example, the search index is rebuilt shortly after you create an Oracle Analytics Cloud instance.

This index readiness check prevents misleading 200 OK responses with empty result sets that might incorrectly indicate that no catalog objects exist.

Direct lookups by object ID in Base64URL format aren’t affected. For example, requests such as GET /api/20210901/catalog/{type}/{id} continue to work even when the search index isn’t ready because these requests don’t rely on catalog search indexing.

Oracle recommends you consider the following when working with catalog list or search requests:
  • Treat 503 Service Unavailable with SearchIndexNotReady as retriable.
  • Don’t interpret 503 Service Unavailable responses with SearchIndexNotReady to mean that the catalog is empty.
  • If a search returns 200 OK with results, use the returned results normally.
  • If a search returns 200 OK with an empty result set, the search index was ready and no matching objects were found.

  • When the catalog object ID is known, use a direct lookup by object ID with Base64URL encoding.