Als je een directe verbinding wilt maken tussen je bronsystemen en de OneStream-omgeving zonder ingewikkelde netwerkconfiguraties of onderhoudsgevoelige IP-whitelisting, is de REST API jouw beste keuze. Steeds meer klanten maken gebruik van REST API-technologie om hun gegevensintegratie te automatiseren, waardoor processen sneller en eenvoudiger worden. De RESTful API, of REST API, maakt gebruik van HTTP-verzoeken om direct te communiceren met andere webservices zonder extra aanpassingen aan het netwerk. Deze verbinding werkt dus direct, zonder extra wijzigingen in de infrastructuur!
Om gebruik te kunnen maken van de RESTful API technologie binnen hey OneStream platform, kan men een Extensibility Business Rule maken die dit verzoeken uitvoert.
REST Request
Zie het volgende code snippet die een voorbeeld laat zien van een 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()
De POST request kan werken als een trigger om bepaalde dataset te genereren o pbasis van de paramters die in de aanvraag worden meegegeven. Nadat deze dataset is gegenereerd, kan een GET REST API worden gebruikt om de daadwerkelijke dataset in JSON-formaat op te halen en deze direct te importeren in de OneStream Import-stappen van je Workflows.
Security
Het voor de hand liggende nadeel van deze REST API is dat deze direct toegankelijk is via het internet, waardoor een veilige verbinding van cruciaal belang is. Een eenvoudige combinatie van een native gebruikersnaam en wachtwoord (Basic Authentication header) is mogelijk niet meer voldoende. Voor onze klanten hebben we OneStream geconfigureerd om gebruik te maken van betere authenticatiemethoden om REST API-verzoeken te verifiëren.
Een voorbeeld van een van deze methodes is het OAUTH 2.0 protocol. Dit maakt gebruik van een zogenaamd authenticatietoken, waarmee gebruikers toegang krijgen tot APIs zonder telkens hun inloggegevens opnieuw in te voeren. Om het OAuth-authenticatietoken te verkrijgen, kan dezelfde Extensibility Business Rule worden gebruikt, waarin een basisgebruikersnaam en wachtwoord worden doorgegeven om uiteindelijk een token te ontvangen. Deze tokenstring kan vervolgens worden gebruikt als een Bearer Token-eigenschap in de Authorization-header van het oorspronkelijke verzoek.
Het onderstaande code snippet laat een voorbeeld van een REST API POST-request zien, waarin de respons het gegenereerde OAuth-toegangstoken bevat.
' 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()
Dit is slechts een voorbeeld van een REST API binnen OneStream. De mogelijkheden om RESTful-technologie te integreren binnen het OneStream-platform zijn eindeloos.
Conclusion
Als je genoeg hebt van het handmatig overdragen van CSV-bestanden van het ene systeem naar het andere en meer wilt weten over de mogelijkheden van REST API in combinatie met OneStream voor het automatiseren van de integratie, aarzel dan niet om contact op te nemen met mij of mijn collega's.
