If you want to create a direct connection between your source systems and the OneStream environment without complicated network configurations or maintenance-sensitive IP whitelisting, the REST API is your best choice. More and more customers are using REST API technology to automate their data integration, making processes faster and easier. The RESTful API, or REST API, uses HTTP requests to communicate directly with other Web services without additional modifications to the network. So this connection works instantly, without any additional infrastructure changes!
To make use of the RESTful API technology within hey OneStream platform, one can create an Extensibility Business Rule that executes these requests.
REST Request
See the following code snippet that shows an example of a parameterized REST API POST request:
Using client As New HttpClient()
' Set authorization header
' client.DefaultRequestHeaders.Add("Authorization", "Bearer " & sBearerToken)
' Create request body
Dim dRestAPIParameters As New Dictionary(Of String, Object)()
dRestAPIParameters.Add("Period", "2024M10")
dRestAPIParameters.Add("Entity", "Groningen")
' Convert the request body to the correct format, application/json in UTF8
Dim jsonRestAPIParameters As String = JsonConvert.SerializeObject(dRestAPIParameters)
Dim content As New StringContent(jsonRestAPIParameters, Encoding.UTF8, "application/json")
'Send POST request
Try
Dim response As HttpResponseMessage = client.PostAsync(url, content).Result
'If the request is successful
If response.IsSuccessStatusCode Then
Dim responseBody As String = response.Content.ReadAsStringAsync().Result
If responseBody.Length > 0 Then
Return JObject.Parse(responseBody)("Status")
Else 'responseBody.Length > 0
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'responseBody.Length > 0
'If the request fails
Else 'response.IsSuccessStatusCode
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'response.IsSuccessStatusCode
Catch ex As Exception
Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
End Try
End Using 'client As New HttpClient()
The POST request can act as a trigger to generate certain dataset o pbased on the paramters provided in the request. After this dataset is generated, a GET REST API can be used to retrieve the actual dataset in JSON format and import it directly into the OneStream Import steps of your Workflows.
Security
The obvious drawback of this REST API is that it is directly accessible over the Internet, making a secure connection critical. A simple combination of a native username and password (Basic Authentication header) may no longer be sufficient. For our customers, we have configured OneStream to use better authentication methods to verify REST API requests.
An example of one of these methods is the OAUTH 2.0 protocol. This uses a so-called authentication token, which allows users to access APIs without re-entering their login credentials each time. To obtain the OAuth authentication token, the same Extensibility Business Rule can be used, in which a basic username and password are passed to eventually receive a token. This token string can then be used as a Bearer Token property in the Authorization header of the original request.
The code snippet below shows an example of a REST API POST-request, where the response contains the generated OAuth access token.
' Define basic credential header for request
Dim sUsername As String = "JWisAwesome"
Dim sPassword As String = "S@nd3r1sG3k"
Dim credentials As String = Convert.ToBase64String(Encoding.ASCII.GetBytes(sUsername & ":" & sPassword))
' Create OAuth token request
Using client As New HttpClient()
'Create the Header of the request
client.DefaultRequestHeaders.Add("Authorization", "Basic " & credentials)
'Create the Body of the request
Dim postbody As String = "grant_type=" + "client_credentials" + "&scope=" + "https://graph.microsoft.com/.default"
Dim content As New StringContent(postbody, Encoding.UTF8, "application/x-www-form-urlencoded")
' Send POST request to Oracle Cloud
Try
Dim response As HttpResponseMessage = client.PostAsync(url, content).Result
'If the request is successful
If response.IsSuccessStatusCode Then
Dim responseBody As String = response.Content.ReadAsStringAsync().Result
If responseBody.Length > 0 Then
Return JObject.Parse(responseBody)("access_token")
Else 'responseBody.Length > 0
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'responseBody.Length > 0
'If the request failed
Else 'response.IsSuccessStatusCode
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'response.IsSuccessStatusCode
Catch ex As Exception
Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
End Try
End Using 'client As New HttpClient()
This is just one example of a REST API within OneStream. The possibilities for integrating RESTful technology within the OneStream platform are endless.
Conclusion
If you're tired of manually transferring CSV files from one system to another and want to learn more about the potential of REST API combined with OneStream for automating integration, don't hesitate to contact me or my colleagues.
