Follow Us on Twitter

Verbind de cloud met Oracle Middleware via REST

Wanneer systemen en applicaties binnen een servicegerichte architectuur worden geïntegreerd, is het van groot belang afspraken te maken over de manier van integreren. Over het protocol, de berichtformaten, datamodellen bijvoorbeeld. Wanneer we praten over Enterprise Application Integration (EAI) is het protocol bij uitstek SOAP. In de wereld van mobile, cloud en social media wordt SOAP veelal beschouwd als te log en inefficiënt. In die wereld is men in de wolken van REST. Oracle zet al een tijd in op cloud en mobile, dus sluipt REST ondersteuning langzamerhand de productstack in. In dit Whitebook bekijken we de REST functionaliteit in de 12c editie van Oracle Fusion Middleware aan de hand van eenvoudige koppeling naar Microsoft OneDrive.

Wat is REST?

REST staat voor Respresentational State Transfer. In tegenstelling tot SOAP is REST geen protocol, maar een set van “architectuurprincipes” die beschrijven waaraan de dataoverdracht en de verbindingen die tot stand komen moeten voldoen. REST is een echt client-server communicatie model. In de praktijk is communicatie van REST gebaseerd op het HTTP protocol (al is dit niet verplicht). REST interfaces beschrijven interfaces gebaseerd op de werkwoorden (verbs) van het HTTP protocol, zoals bijvoorbeeld GET, POST, PUT, DELETE.

REST interfaces zijn stateless. Dit betekent dat iedere transactie op zichzelf staat en de server geen state-informatie bijhoudt van de client. De client moet dus alle benodigde informatie in haar requests mee te sturen naar de server.

Verder zijn REST interfaces niet echt gestructureerd. De input en output payloads zijn veelal niet aan standaarden onderhevig, en verschillen per interface. De enige vorm van standaardisatie zit in het JSON formaat (JavaScript Object Format) dat vaak (maar niet altijd) wordt gebruikt voor het beschrijven van het in- of output-formaat.

Waarom is REST interessant?

De vraag is waarom we ons naast het gestructureerde en gestandaardiseerde SOAP protocol moeten bezighouden met de niet echt gestandaardiseerde REST services? Het antwoord is cloud. Bijna alle cloud services, social medianetwerken en apps hebben wel een API (application programming interface) beschikbaar die benaderbaar is op basis van REST services. De APIs zijn gespitst op het hebben van een simpele interface, zonder veel overhead die eenvoudig in (simpele) mobile toepassingen te gebruiken zijn. SOAP is te log en hier minder geschikt voor.

Veel gebruikte cloud diensten zijn de Cloud Storage services zoals Google Drive en Microsoft OneDrive. Deze services hebben een API beschikbaar die je in staat stelt third party applicaties te koppelen. Hetzelfde geldt overigens ook voor bijvoorbeeld Twitter, Facebook, Evernote.

REST in Oracle Fusion Middleware 12c

Oracle zet hard in op mobile en zo ook met de nieuwe versie van Oracle Fusion Middleware 12c. REST mag dus niet ontbreken. De SOA Suite van Oracle is grotendeels gebaseerd op het SOAP protocol. Grotendeels, want REST is niet helemaal nieuw binnen de Fusion Middleware stack: de Oracle Service Bus kan al sinds jaar en dag REST services implementeren en gebruiken. Echter, in de 12c release van de SOA Suite stack wordt REST meer mainstream door de introductie van de REST adapter die op eenvoudige manier in de SOA composites kan worden gebruikt.

SOA Suite 12c REST Adapter in JDeveloper

Deze adapter verzorgt de vertaling van REST naar XML zodat er moeiteloos gebruikgemaakt kan worden van REST services in de SCA componenten zoals BPM, BPEL en Mediator. In dit Whitebook wordt de REST functionaliteit in Oracle SOA Suite 12c aan de tand gevoeld door te integreren met de OneDrive service van Microsoft.

REST in de praktijk

Met behulp van de REST adapter in Fusion Middleware kan er direct worden gekoppeld aan de cloud diensten die veel gebruikers al benutten. Een praktische casus is het opslaan van documenten uit een Oracle SOA Suite SCA component in de OneDrive online opslag van Microsoft.

Microsoft OneDrive is –zoals vele cloud diensten- benaderbaar via een REST API. De MSDN OneDrive REST API staat beschreven op de developer-pagina’s van MSDN.

Het begint allemaal met het aanmaken van een applicatieprofiel bij Microsoft (zie MSDN Developers Application Center).

Aanmaken van een applicatieprofiel bij Microsoft

Bij het aanmaken van het applicatieprofiel worden geheime sleutels verkregen, die moeten worden gebruikt in de communicatie met de API. Immers, REST is stateless en de client moet altijd alles meegeven aan de server wat nodig is voor het request.

Geheime codes aanmaken Microsoft applicatieprofiel

Nagenoeg alle REST APIs van cloud diensten vereisen dat de gebruiker expliciet de applicatie toegang moet geven tot zijn account. De gebruiker geeft als het ware toestemming dat de applicatie acties in de cloud dienst kan uitvoeren namens deze gebruiker. Deze vorm van authenticatie wordt OAuth genoemd.

Allereerst moet de gebruiker de applicatie autoriseren op zijn account. Waar de applicatie allemaal toegang tot krijgt (de scope) wordt expliciet gespecificeerd tijdens het autorisatieproces. Als dit proces succesvol wordt doorlopen, verkrijgt de applicatie een autorisatiecode toegestuurd op een vooraf ingesteld endpoint (bijvoorbeeld een Service Bus of SOA composite).

De gebruiker kan de applicatie autoriseren door in een scherm van de applicatie de volgende URL te openen:

https://login.live.com/oauth20_authorize.srf?client_id=YOUR_ID&scope=wl.signin%20wl.skydrive%20wl.offline_access%20wl.basic&response_type=code&redirect_uri=http://www.whitehorses.nl/whitebooks/soa/osb/auth_callback

In deze URL staan de verkregen client_id en de vereiste scopes. De gebruiker krijgt nu de vraag de applicatie te autoriseren.

Microsoft sign in dialog

Microsoft OAuth application premission dialog

In de bovenstaande figuur zien we waar de applicatie allemaal namens de gebruiker toegang tot wil. In dit specifieke voorbeeld stonden de volgende scopes in de request (scope=wl.signin%20wl.skydrive%20wl.offline_access%20wl.basic). Deze scopes staan beschreven in de API documentatie, en betekenen dat deze applicatie toegang krijgt tot het account (wl.signin) de basis profielgegevens kan ophalen (wl.basic), OneDrive (voorheen Skydrive) kan benaderen (wl.skydrive) en dit ter aller tijden kan doen, zelfs als de gebruiker niet is ingelogd (wl.offline_access).

Wanneer de gebruiker op “Yes” drukt wordt een autorisatiecode naar het opgegeven endpoint (http://www.whitehorses.nl/whitebooks/soa/osb/auth_callback) gestuurd.

Werken met de REST API en de REST Adapter

Nu we de autorisatie van de gebruiker hebben, kunnen we de API gaan gebruiken in de REST adapter. Microsoft’s documentatie geeft voorbeelden hoe de OneDrive API aan te roepen is. Deze voorbeelden zijn perfect bruikbaar om de REST Adapter van Oracle in te richten.

Als voorbeeld nemen we het verkrijgen van een autorisatietoken op basis van de eerder verkregen autorisatiecode. Dit token is uiteindelijk nodig om toegang te krijgen namens de gebruiker tot de API. Dit token is maar een korte tijd geldig, en moet dus regelmatig opnieuw worden verkregen. Doordat we toegang hebben gekregen tot de wl.offline_access scope (“Access your info anytime”), kunnen we bij het verlopen van de token direct een nieuwe verkrijgen zonder tussenkomst van de gebruiker.

De API-documentatie illustreert deze operatie met het volgende voorbeeld:

Het request bericht:

POST https://login.live.com/oauth20_token.srf
Content-type: application/x-www-form-urlencoded
client_id=0000000603DB0F&redirect_uri=http://www.contoso.com/callback.php&client_secret=LWILlT555GicSrIATma5qgyBXebRI&code=2bd12503-7e88-bfe7-c5c7-82274a740ff&grant_type=authorization_code

En het antwoord (in JSON formaat):

{
    "token_type":"bearer",
    "expires_in":3600,
    "scope":"wl.signin wl.basic",
    "access_token":"EwCo...//access token string shortened for example//...AA==",
    "authentication_token":"eyJh...//authentication token string shortened for example//...93G4"
}

Over het request bericht weten we nu het volgende:

  1. De base URI is https://login.live.com
  2. Het “resource path” is aouth20_token.srf
  3. Het Content-Type is expliciet gezet op “application/x-www-form-urlencoded”
  4. Het is een HTTP POST operatie
  5. De request-invoer is in de vorm van URI parameters.

Dit kunnen we gebruiken in de configuratie van de REST adapter:

Create REST Binding Oracle 12c

Vervolgens moeten we een POST operatie gaan toevoegen:

Create REST adapter: Add POST Operation Create REST adapter

De input parameters kunnen handmatig worden gedefinieerd, maar via de Native Format Builder wizard kunnen deze ook worden gegenereerd.

Create REST adapter - Native Format Builder wizard

Het voorbeeld van Microsoft bevat een URI example, dus die is hier te gebruiken.

Native Formate Builder URI sample

De opgegeven URI wordt opgezet naar afzonderlijke request parameters, en een XML schema definitie. Dit schema definieert de invoer voor de REST adapter, en de invoer die we vervolgens gebruiken in de SOA composites.

Analoog aan de invoer, definiëren we ook de uitvoer aan de hand van de Native Format builder. Echter hebben we hier te maken met een voorbeeld JSON response. Door JSON Interchange Format te kiezen, en het voorbeeld uit een bestand in te laden in de wizard wordt op basis van deze invoer een XML schema gecreëerd die de uitvoer netjes in XML teruggeeft als uitvoer van de REST Adapter.

Create REST adapter - Native Format Builder wizard step 3 - Sample JSON payload

Voor de volledigheid kan een foutuitkomst ook nog worden gedefinieerd. De response definitie ziet er dan als volgt uit:

Create REST adapter - Native Format Builder wizard - definitie foutuitkomst

En het eindresultaat bestaat uit een gedefinieerde REST operatie op een Resource path op een host:

Create REST binding eindresultaat met gedefinieerde REST operatie op Resource path

Op deze manier kunnen verschillende operaties (GET, PUT, POST, DELETE) op verschillende Resources op een server allemaal worden ondergebracht in een enkele REST adapterdefinitie.

De REST adapter heeft wel een beperking. De in- en output definities voor de REST services zijn XML of URL encoded of JSON. Voor het opslaan van een bestand in de OneDrive cloud is echter een PUT operatie nodig met zowel URL encoded input en de inhoud van het bestand als payload van het request bericht. Dit is helaas (nog) niet mogelijk in de huidige versie van de REST adapter.

Gelukkig bevat de SOA Suite ook de Service Bus. In een SOA-architectuur wordt de Service Bus veelal ingezet om de communicatie tussen verschillende functionele domeinen, of systemen te verzorgen. Het verzorgt het transport, en eventueel de protocoltranslatie tussen de systemen. Op deze manier hoeft de service orkestratielaag zich niet bezig te houden met technische communicatie tussen verschillende systemen. In deze context doet de Service Bus de protocoltranslatie tussen SOAP en REST, net zoals de REST adapter dat al out of the box doet. De Service Bus is vrijer m.b.t. het gebruik van REST services.

Om een bestand op te slaan in de OneDrive cloud moet er eerst een HTTP messaging Business Service worden gemaakt:

Create HTTP messaging Business Service - step 1

Create HTTP messaging Business Service - step 2

Create HTTP messaging Business Service - step 3

In de OSB moet wel veel meer zelf worden gedaan. Als we kijken op [1] naar de interface voor het opslaan van een document in OneDrive zien we gelukkig dat het een eenvoudige interface is:

PUT https://apis.live.net/v5.0/me/skydrive/files/HelloWorld.txt?access_token...

Hello, World!

In dit geval moeten we dus handmatig de URL (voor de bestandsnaam) en de query-parameter voor de ACCESS_TOKEN manipuleren in de OSB. Dit is eenvoudig te doen door de standaard aanwezige $outbound context variabele aan te passen in de OSB proxy service.

$outbound/ctx:transport/ctx:uri

Voor de URL, en

$outbound/ctx:transport/ctx:request/http:query-parameters/http:parameter@name

$outbound/ctx:transport/ctx:request/http:query-parameters/http:parameter@value

voor URL request parameter: de ACCESS_TOKEN. Door een Route node te gebruiken in de OSB proxy is de $body de inhoud van de variabele. De response van de aanroep is in het JSON formaat. Het zou bewerkelijk zijn als dit response bericht handmatig zou moet worden omgezet in XML. Gelukkig beschrijft Jeff Davies in zijn blog Using JSON with Oracle Service Bus REST Services een manier om JSON om te zetten naar XML met een eenvoudige Java Callout. Het gaat te ver om hier alle details van REST in de OSB te bespreken. Ook hiervoor heeft Jeff Davies een uitstekende OSB REST Tutorial geschreven.

Het bestand dat we uiteindelijk willen uploaden kan bijvoorbeeld ingeladen worden via een FileAdapter, waarvan de bestandslocatie  wordt meegegeven als invoer voor de OSB proxy.

OSB proxy

We hebben nu de “complexe” PUT-operatie geïmplementeerd in de Service Bus, en het verkrijgen van de tokens middels de REST adapter. Nu kunnen we het samenvoegen in een service orkestratie in BPEL.

BPEL composite

Deze composite verzorgt de aanroep naar de REST adapter en roept vervolgens de Service Bus aan. Zo verkrijgen we toegang en uploadt het een bestand naar de OneDrive cloud.

Conclusie: en de REST …?

De cloud en de diensten die er op worden aangeboden zijn nagenoeg altijd ook benaderbaar via een REST API. Om vanuit Oracle’s Middleware van deze API gebruik te maken was men tot versie 12c aangewezen op de Oracle Service Bus.

Met de komst van 12c, en de REST adapter is het gebruik van REST APIs een stuk eenvoudiger geworden. De REST adapter stelt je in staat snel een adapter in je SOA Composite te creëren, zelfs op basis van de aanwezige voorbeelden uit de API documentatie van de API-aanbieder.

Dit Whitebook illustreert het gebruik van de REST adapter en de mogelijkheden er van aan de hand van een eenvoudig voorbeeld. Door gebruik te maken van de beschikbare voorbeelden in de REST API documentatie van de serviceaanbieder kan de adapter worden geconfigureerd. De REST adapter is alleen nog niet perfect. Meer geavanceerde API aanroepen die de query parameters combineren met een payload worden helaas nog niet ondersteund. Voor de meer geavanceerde API-calls kan de Service Bus worden ingezet. De Service Bus kan met een messaging service ook REST service implementeren en consumeren. Dit is alleen bewerkelijker.

Concluderend kan worden gezegd dat de REST toolset uit de Oracle SOA Suite 12c uw applicatie integratie kan uitbreiden naar de cloud en haar cloud services.

Referenties

Waardering:
 

Reacties

Nieuwe reactie inzenden

De inhoud van dit veld is privé en zal niet openbaar worden gemaakt.

Meer informatie over formaatmogelijkheden

CAPTCHA
Deze vraag is om te testen of u een persoon bent en om spam te voorkomen
Image CAPTCHA
Enter the characters shown in the image.