About Catalog REST APIs

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.

About Catalog REST APIs 503 Service Unavailable Responses

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.