Automate & Elevate with Oracle Analytics REST APIs - part I

REST (REpresentational State Transfer) APIs (Application Programming Interface) are a way for software systems to communicate and share data over the internet using HTTP requests. REST APIs enable different systems to exchange data in a standardised way.  Simply put, an API is a set of rules which enable different software applications to communicate with each other defining how the software applications should interact without having to know about the internal complexities of each application. 

This analogy further explains an API; think of an API as a waiter in a restaurant. When you (the client) want to order food which is analogous to requesting information or services, you do not need to fully understand what the Chef needs to do to get your order prepared.  You, the client made your request to the waiter who acts as an intermediary (in the way that an API is the go-between) ensuring that communication between the client and the kitchen is executed and then returns the food ordered to the client.

Photo by Bimo Luki on Unsplash

Some key aspects of REST APIs:

1. They use HTTP methods like GET, POST, PUT, DELETE to perform operations.
2. Data is structured in either JSON or XML format.
3. APIs are organised around resources which are identified by URIs.
4. APIs are stateless, meaning no client context is stored on the server between requests.

The January 2024 update includes an extension to the available REST API endpoints that now provide catalog management capabilities. In Oracle Analytics Cloud, REST APIs allow external applications to integrate with and extend the capabilities of OAC. Some examples of how REST APIs are used:
​

1. Catalog object deployment and management of object permissions
2. OAC system settings configuration
3. Querying data from OAC datasets and subject areas. The API can return data in JSON format.
4. Automating processes by chaining together sequences of API calls.

Mike Durran from the Oracle Analytics Product Management team has put together a video available on YouTube that walks through these endpoints.

REST APIs provide a standardised way for Oracle Analytics Cloud to exchange data and interoperate with other systems. The APIs allow OAC capabilities to be leveraged from external apps and workflows. REST APIs can help enable clean handoffs between developers and production support teams for Oracle Analytics Cloud deployments, without the production support teams requiring extensive OAC expertise from the operational perspective of Oracle Analytics.

Catalog Rest APIs

Some of the new REST API endpoints released in the January 2024 update that now allow for catalog management. Here is a list of the new Oracle Analytics Cloud REST API endpoints:
​

1. Copy a Catalog item
2. Create a folder
3. Delete a folder
4. Get Catalog item ACL
5. Get Catalog item details
6. Get Catalog item by type
7. Move a Catalog item
8. Update a Catalog item ACL

​The curl command below is an example of how one of these endpoints looks like.

List Workbook Catalog Objects

The {{OAC_URL}} portion of the URL (above) to use in the REST API endpoints can be retrieved from your Analytics Instance detail page as below:

​Developers can build automated deployment pipelines and operations runbooks that call OAC REST APIs to perform releases. For example, the pipeline can use APIs to validate the system health, check for availability of required roles/capacity, import metadata like dashboards or reports, and switch traffic to the new version. 

The operations team does not need deep application knowledge, just the ability to invoke APIs and monitor for errors. The actual deployment logic is encapsulated in code and triggered through API calls. This allows a clear separation of development teams from production environments - developers own building the logic and automation leveraging their OAC expertise, while operations teams focus on running and monitoring the operational aspects.

The APIs serve as the interface layer between the two. This prevents fragile handoffs where operations need to learn and understand OAC internals, rely on manual processes or even rely upon the development teams to carry out these activities in production environments. Access to production can be minimised once APIs are implemented.

Overall, OAC REST APIs enable easier collaboration between developers and production teams. Releases can be made reliable and repeatable through automation using APIs, reducing risks and errors caused by manual processes. The APIs abstract away the complexity and provide self-service capabilities to operations teams.

The second part of this blog will dive into more technical detail on how these REST APIs are set up  using an API client tool to interact with the API endpoints. We'll also look at how these REST APIs can be used  by operations teams.