Getting Started with REST API’s using Python

Duncan Brock
Brovanture EPM Consultant

EPM Automate and REST APIs have been provided by Oracle to enable System Administrators to manage Oracle EPM Cloud applications remotely and to automate mundane tasks.

Although EPM Automate is great, it is mostly used for batch scripting and is limited in its capabilities.  REST APIs open the door to a whole world of additional programming languages, but the Oracle documentation only scratches the surface of what is possible. Supported languages like cURL and Groovy are relatively new and unknown, and although Java is documented, Python isn’t.  Considering Python is one of the most popular programming languages in the world this is a major omission.  Let’s delve into a quick “Getting Started” guide to help you to utilise this programming powerhouse.

Before we begin, I’m going to assume that you have Python already installed. If not, go and download it here. Once you have done that, you will need to install the Requests module. This is going to make life a lot easier when making REST API requests further down the line! You can do this using pip – a package installer that you run in the command shell.

pip install requests

 

Sending a simple GET request using the Planning in the Oracle EPM Cloud API

A REST API is essentially a specific URL that has been developed to enable developers to retrieve (GET) or send (POST) information. REST (REpresentational State Transfer) is a sort of architecture or set of rules that defines the API.

Let’s get started by opening a new Python (.py) file using any text editor (I recommend Notepad++ or an IDE such as Visual Studio Code). We’ll start at defining some variables.

# Import the Requests module into the current Python script
import requests

# Define the login credentials.
username = 'admin'
password = 'mypwd'
iddomain = 'a123456'
serv_url = 'https://planning-' + iddomain + '.pbcs.em2.oraclecloud.com'

# Set up a new "web" session and define the Authorisation header with credentials
session = requests.Session()
session.auth = (iddomain + '.' + username, password)

Next, we’ll do a simple GET request that returns all the API versions. This will be important later as the latest API version will need to be included in the URL.

# Returns a JSON response of the GET request using the API defined below
api = '/HyperionPlanning/rest/'

json_response = session.get(serv_url + api).json()
print(json_response)

If you run this script you will be presented with a list of items. Each item is an API version. We want to find the latest API version and we can do this with a simple “for” loop.

# Iterate through each item to find the latest version
for api_version in json_response['items']:
    if api_version['isLatest'] == True:
        latest_api_version = api_version['version']
        break

print(latest_api_version)

Run this script and you’ll see that the latest version we get is “v3”. We can now use this in other API requests.

 

Getting and Updating Substitution Variables

Let’s put this into practise and write a script that updates a Substitution Variable. We’ll start by getting a list of all the current variables using a GET request.

# A simple GET request to retrieve all sub vars in the Planning Application
application = 'Vision'
api = f'/HyperionPlanning/rest/{latest_api_version}/applications/{application}/substitutionvariables'

json_response = session.get(serv_url + api).json()
print(json_response)

Run this and you’ll see a JSON response with a list of variables, their values and which Plan Type they are set for (ALL is Application Level).  Let’s update one of these Substitution Variables.

# We need to create a dictionary to have as the content to POST
payload = {
    'items': [{
        'name': 'CurrMth',
        'value': 'Feb',
        'planType': 'ALL'
    }]
}

# Next we need to POST this along with the content using the same API as the GET request. We will send the data as a json content type
r = session.post(serv_url + api, json=payload)

# To see if it updated successfully you can print the status code. 204 is successful. 200 is also successful but it means nothing was updated.
print(r.status_code)

That’s it!  You now have the skills to apply this to any API in the REST API documentation. Have fun coding!

Until next time

Duncan