One API is de benaming van Synigo Pulse voor een manier om een applicatie te ontsluiten. Denk bijvoorbeeld aan applicaties zoals AFAS, Dynamics, PeopleSoft, Exact, Magister, Canvas en nog veel meer! Deze uniforme manier om systemen te ontsluiten bestaat uit drie onderdelen, te weten:
- Metadata;
- Informatie;
- Beveiliging.
Op het moment dat je deze drie manieren op een standaard manier invult. Ben jij in staat om naadloos jouw API te integreren in jouw eigen Synigo Pulse portal. Metadata is de benaming die we geven aan gegevens die informatie beschrijven. In het geval van One API gaat het om informatie die beschrijft hoe de API eruitziet. Bijvoorbeeld op welk adres de API beschikbaar is.
Voorbeeld van een One API
Je hebt in AFAS op basis van de gebruiker openstaande taken. Dit gegeven kan je met een One API in de Workspace zetten. Je hebt dan natuurlijk wel informatie nodig van AFAS. Om het aantal taken voor een specifieke gebruiker op te halen, moet je hierom een unieke sleutel van de gebruiker meesturen, zodat de Workspace weet over wie het gaat.
De Workspace is in staat om bekende informatie van de gebruiker mee te sturen, zodat de service hier iets mee kan doen. Denk hierbij aan een naam, gebruikersnaam en specifieke instellingen. Deze gegevens krijgt de Workspace door, op het moment dat de betreffende gebruiker succesvol inlogt binnen de Azure AD. Als je wilt kan je zelfs tijdens dit proces hele specifieke informatie laten teruggeven, zoals een personeelsnummer. Deze informatie kan je vervolgens aan de Workspace doorgeven om er weer iets mee te doen.
Per applicatie verwachten we een Open Api service. Hiermee wordt de informatie namelijk opgehaald. Nu we de actie en applicatie hebben beschreven, kunnen we met behulp van Open Api metadata (=informatie) daadwerkelijk de informatie ophalen. Bij Synigo Pulse praten ze altijd over verschillende widgets. En je wilt een widget gaan voorzien van de opgehaalde informatie.
Je ziet dus al bij huidige widgets dat er ook gebruik wordt gemaakt van een Open Api. Denk bijvoorbeeld aan de widget agenda en notificaties. Die halen van een bepaalde applicatie informatie (metadata) op door middel van de Open Api.
Om op standaard manier om te gaan met Open Api's verwachten we elke keer dat:
- De modellen van de informatie worden op een gestandaardiseerde manier aangeboden
- Tijdens de informatie-uitwisseling geeft het model aan van welk soort het is.
Dit is de gestandaardiseerde manier
Voor de informatie uitwisseling maken we gebruik van het zogenoemde Odata protocol:
Het Open Data-protocol (OData) is een best practice voor het structureren en bevragen van REST API's. OData maakt het makkelijker om interoperabele REST-implementaties te bouwen, waardoor data die via API’s wordt uitgewisseld op een gestandaardiseerde manier weergegeven kan worden.
Door te standaardiseren weten we hoe de data binnenkomt en hoe deze te verwerken. Echter, we weten nog niet wat er in de data staat. Hier komen we achter door de zogenoemde @odata.type. Dit is metadata over de informatie die verstuurd is. Op het moment dat het type informatie bij ons bekend is, kunnen we het op de juiste manier verwerken.
Informatiestandaarden
Het liefst maken we gebruik van informatiestandaarden. Met deze werkwijze bouw je een eigen API die handig is voor je Workspace en ook voor andere afnemers. De principes om een standaard te ondersteunen gaat als volgt:
- Is er een standaard waarin de informatiebehoefte kan worden ondervangen? Indien ja; dan gebruik je die. Indien nee; kijk naar andere mogelijkheden.
- Mocht er industriestandaard gevonden kunnen worden, dan probeer je de modellen van de Microsoft Graph over te nemen.
- Mocht dat niet lukken kies je een eigen model.
In je Workspace authentiseer je jezelf via Microsoft Azure AD. Zodra dit succesvol gebeurt, krijg je een unieke security token van Microsoft. Hierin staat onder andere wie jij bent en wat je mag. Of dat jij iets mag ligt aan de machtigingen welke aan jouw mailadres zijn gekoppeld. Er wordt gekeken of iemand jouw mailadres heeft gemachtigd om toegang te krijgen tot de Azure AD. De applicatie staat daar onder de naam “Your Digital Workplace” onder het tabje "Enterprise Applications".
Je kan zelf een applicatie toevoegen onder "App registrations". Als je dat doet, ben je in staat om deze gegevens te gebruiken om in een programma je Azure AD te benaderen en gebruikers te authentiseren. Hierna kan je de Applicatie “Your Digital Workplace” toegang geven tot jouw eigen gemaakte applicatie. Op deze manier leg je een vertrouwensband en zeg je eigenlijk: een token van mijn portal, mag ik omruilen voor een andere token, waarmee gebruikers van de Workspace toegang krijgen tot mijn applicatie. Dit principe noemen we ook wel Exchange Tokens, omdat je als het ware tokens uitruilt.
Jouw eigen API maken
Onderstaande heb je nodig om jouw eigen API te maken.
- Een Azure App Registratie;
- Een tool om code mee te schrijven (Visual Studio);
- Een Azure Web App;
- Een Backoffice software.
Als eerste moeten we een app registratie aanmaken in Azure. Deze registratie bevat alle informatie, die de API straks nodig heeft om Verzoeken vanuit het portal toe te staan en Azure te benaderen.
Stap 1: aanmaken registratie
- Ga naar https://portal.azure.com en vervolgens naar het onderdeel Azure App Registrations (https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlad).
- Maak een nieuwe App Registratie aan, kies hier een leuke naam. Hieronder zie je het voorbeeld van de app "Synigo Universal API" genoemd.
- Kies "Add a permission". Hier zie je een lijst van alle API's die je tot je beschikking hebt. Kies hier Azure Service Management. In de screenshot hebben we bijvoorbeeld al toegang gegeven tot andere zaken als de Microsoft Graph en Dynamics.
- Op het moment dat de API is toegevoegd, dien je toestemming te geven om deze ook daadwerkelijk te gebruiken. Klik hierom op de knop "Grant admin consent for [jouw organisatie]"
- Stel nu je API in, zodat andere toepassingen daar ook gebruik van kunnen maken.
- Kies "Add a Scope". Geef deze een naam en omschrijving. Klik tot slot op "OK".
- Voeg de "Client ID" toe van Your Digital Workplace onder "Add a Client Application". Deze kan je vinden onder Enterpise applications.. Het is het ID dat start met 1ad en eindigt met a3e.
- Maak een wachtwoord aan onder "Certificates and Secrets". Door onder "Certificates & Secrets" te kiezen voor "New client secret". Bewaar dit wachtwoord op een veilige plek want je hebt dit later nodig.
Je hebt nu een app registratie aangemaakt. Vervolgens dien je een API te maken. Hier heb je wel wat ontwikkel kennis voor nodig. We gaan Open Source voorbeelden op Github zetten. Voor nu beschrijven we hier de zaken die je moet doen om een API te bouwen.
Bouw je API in je favoriete omgeving
De taal instelling maakt niet veel uit, aangezien je in code taal gaat werken. Code JSON/REST taal is universeel.
Geef een bepaald model terug
Het One API Concept verwacht bepaalde manieren waarop de informatie binnenkomt, zodat het succesvol de data in een bepaalde widget kan tonen.
Maak je omgeving secure
De One API vewacht dat je API is beveiligd middels "Bearer JWT tokens". Deze zijn te verkrijgen via het Exchange Token principe. Hieronder staan een aantal directe links naar meer informatie en handige tools als je met JWT tokens gaat werken. Voor dit scenario heb je in stap 1 je Client Id en Client Secret aangemaakt.
- https://docs.microsoft.com/nl-nl/azure/active-directory/develop/scenario-token-exchange-saml-oauth
- https://docs.microsoft.com/nl-nl/azure/active-directory/develop/msal-overview
- https://jwt.io
Maak je omgeving aansluitbaar
We moeten kunnen afleiden welke API endpoints je beschikbaar hebt gesteld. Hiervoor verwachten we een Open API beschrijving, waar in staat waar de API te vinden is en welke parameters er verwacht worden. Een mooie tool hiervoor is Swagger. Je vindt onder ander op nuget veel Swagger implementaties in de taal en platform naar je keuze.
Nu je API klaar is en hij draait in een omgeving (beschikbaar vanuit het internet) kan je je API koppelen.
In het CMS ga je naar "Organization Settings" en dan ga je naar de tab "Api Settings". Hier kan je de volgende gegevens invoeren.
Application Id | Vul hier het Id van de applicatie in, welke je in stap 1 hebt aangemaakt. Ter voorbeeld ziet het er zo uit "api://91211266-f2b6-4abf-ae07-41258bd72989". |
Swagger Url | Vul hier de url in van het adres waar we de "Open ID" documentatie kunnen vinden. Deze URL kan vrij toegankelijk zijn of afgeschermd, middels dezelfde JWT bearer token van de rest van je API. |
Base Url | Vul hier het root adres in van je API. We moeten wel weten waar we de API kunnen aanroepen. |
Service Health Endpoint | Optioneel kan je een Service Health endpoint opgeven. Op het moment dat je "Check Service Status" aanroept, roepen we je API aan en geven je de mogelijkheid om de status van je API door te geven. |

Op het moment dat je de bovenstaande velden hebt ingevuld, kan via "Refresh API Definition" de koppeling tussen Synigo Pulse en jouw One API verversen. Als alles goed is ingesteld zie je onderstaande informatie verschijnen. Het bevat een lijst van alle beschreven API's en welke parameters de individuele API's verwachten.
Op de plek van de parameters kan je een vaste waarde invullen of via het pijltje dat naar beneden wijst een aantal suggesties naar voren halen. De suggesties die door de API worden aangereikt of placeholders waar automatisch de gebruikersgegevens worden ingevuld.
Als laatst is mogelijk om een waarde van een claim mee te geven {user.claims['naam'].Value}. De claims die we voorhanden hebben zijn die, die tijdens het inloggen vanuit je Azure omgeving aan de portal worden meegegeven. Je kan hier zelf extra claims aan meegeven, bijvoorbeeld studentnummer of locatie.

Het koppelen van een API aan een widget, gaat op de volgende manier:
- Maak een One API Connection onder Organization Settings => Connections (als de connectie nog niet bestaat, dien je deze eerst aan te maken);
- Koppel de One API Connection aan de widget.
De reden dat dit in 2 stappen is opgedeeld, heeft te maken met het feit dat de connecties redelijk technisch van aard zijn en de widgets functioneel. Zo kan iemand alle connecties klaar zetten en voor iedereen de gewenste connectie kiezen.
Zo maak je een nieuwe One API connectie

Selecteer de juiste service

En koppel de connectie aan de gewenste widget. Je ziet hier een lijst van allerlei soorten connecties. De onderste twee zijn de One API Connecties.

Deze Widgets zijn momenteel beschikbaar voor One API
Grades Widget | Toon de laatst behaalde cijfers van een student |
Calendar Widget | Toon een agenda overlay uit een ander bronsysteem |
My People Widget | Toon een lijst van personen in een bepaalde context |
My List Widget | Toon iedere willekeurige lijst (met kinderen) van gegevens. |
Notification | Toon een notificatie uit een bepaald bronsysteem |
One Search | Sluit een bronsysteem op de one search aan |