Wat is exposed API?

Concept

Algemeen

De exposed API is een beveiligde interface waarmee een externe applicatie zoals een CRM-systeem dossierinformatie kan opvragen en/of acties kan uitvoeren in lopende dossiers. Dit gebeurt via https/JSON, d.w.z. de interactie verloopt via URL en de info (payload) wordt aangeleverd in JSON-formaat.

Relatie met connectoren

Functioneel en technisch vertoont de exposed API een sterke gelijkenis met de connector in die zin dat beiden een interface tot stand brengen tussen de Skryv applicatie en een externe applicatie. Het verschil is dat bij de connector de interactie start vanuit de workflow in de Skryv applicatie, terwijl bij de exposed API de interactie start vanuit de externe applicatie.

Relatie met interne API

Naast de exposed API die bedoeld is voor communicatie met externe applicaties, bestaat er ook een applicatie-interne API die gebruikt wordt voor communicatie tussen backend en de frontend webtoepassingen (frontoffice en backoffice). Deze interne API is niet beschikbaar voor technische gebruikers (API consumers). Het gaat hier dan ook twee strikt gescheiden modules binnen het Skryv platform (platform-rest & platform-exposed-rest).

Functies van de exposed API

De Skryv exposed API bevat een waaier aan functionaliteiten die je kan opdelen in twee categorieën.

1. Informatie opvragen ('GET'). Bijvoorbeeld dossierinformatie aanleveren die opgeslagen zit in formulieren, communicaties doorsluizen, de status van het dossier opgeven, enzovoort.

2. Informatie aanbieden ('POST'). Bijvoorbeeld een gebeurtenis of signaal in het CRM-systeem triggert een actie binnen de Skryv applicatie.

Klik hier voor een gedetailleerd overzicht van alle mogelijkheden.

Exposed API beveiliging

De exposed API van de Skryv applicatie maakt het mogelijk om gevoelige data op te vragen, wat strikte veiligheidsmaatregelen vereist. De OWASP-methodologie wordt gebruikt om beveiligingsrisico's systematisch te identificeren en aan te pakken. Alleen geauthenticeerde technische gebruikers kunnen de API aanspreken, en elke API-call wordt gelogd. Netwerkbeveiliging wordt verzorgd door een firewall die beschermt tegen ongewenste requests en kwaadaardige activiteiten. Verder kan de API gateway uitgebreid worden met throttling functionaliteit om het aantal requests te beperken en zo de belasting te beheersen en misbruik te voorkomen.

Opbouw van API calls

Het aanspreken van de exposed API functionaliteiten gebeurt via API calls. Deze worden uitgestuurd vanuit de externe applicatie via HTTPS en nemen de vorm aan van URL’s. Onderstaande API call vraagt een lijst van alle dossiers binnen de applicatie op.

https://yourApp.skryv.com/exposed/v1/dossiers?page=0&size=20

Dergelijke API calls kunnen niet zomaar uitgevoerd worden. Er ontbreekt nog wat contextuele informatie.

1. Type call, bijvoorbeeld GET (info opvragen) of POST (info aanbieden).

2. Je moet specificeren in welk formaat je de API-response verwacht, bijvoorbeeld HAL-JSON.

3. Authenticatie, de externe applicatie moet beschikken over een technische gebruiker gedefinieerd binnen de Skryv applicatie. Bij het versturen van de API call moet je dus de credentials voor die technische gebruiker meegeven, bijvoorbeeld een bearer token.

De werkelijke API call zal er dus als volgt uitzien.

curl -X 'GET' \
 'https://yourApp.skryv.com/exposed/v1/dossiers?page=0&size=20' \
 -H 'accept: application/hal+json' \
 -H 'Authorization: Bearer ***...'

Korte toelichting:

• Op lijn 1 wordt het type request aangeduid (GET).

• Op lijn 2 volgt de inhoud van de call.

• Op lijn 3 wordt een header toegevoegd aan de call om het response formaat te specificeren.

• Op lijn 4 wordt een header toegevoegd aan de call om de authenticatie te specificeren.

Technische gebruiker

De exposed API geeft toegang tot gevoelige dossierinformatie. Vandaar dat enkel een geauthenticeerde technische gebruiker (ook wel API consumer) de exposed API kan aanspreken. Onderstaande tabel toont de gelijkenissen en verschilpunten tussen een gewone (menselijke) backoffice of frontoffice gebruiker en een technische gebruiker. Klik hier voor meer informatie over hoe je een technische gebruiker aanmaakt.

API-response

Na uitsturen van de API call komt er een response terug, meestal in het HAL-JSON formaat.

Onderstaand voorbeeld toont de response op een API call die een dossierlijst opvraagt. De response vertoont typisch volgende structuur waarbij de embedded resource wisselt afhankelijk van de API call die je maakt.

• “_embedded”: HAL-kenmerk dat een embedded resource bevat. In dit geval de lijst met dossiers.

• “dossiers”: lijst met dossiers, elk dossier is een map met een hele resem eigenschappen. Hierin staan ook links waarmee je gerelateerde info kan ophalen (zo kan je bijvoorbeeld doorklikken naar details voor een specifiek formulier of een specifieke taak).

• “_links”: HAL-kenmerk met links. In dit geval zijn het links die je kan gebruiken om doorheen de resultatenlijst te navigeren (eerste pagina, volgende pagina, laatste pagina, etcetera).

• “page”: metadata over de paginering, bijvoorbeeld het totaal aantal dossiers, het totaal aantal pagina’s.

Merk op dat de API-response slechts één dossier bevat. De opgevraagde dossierlijst telt twee dossiers in totaal, maar er wordt slechts één per pagina toegelaten en we kunnen slechts pagina per pagina ophalen.

{
 "_embedded": {
 "dossiers": [
 {
 "id": "1309819d-d30f-4248-b8db-5f7e833378f3",
 "label": "EXPOSED-TEST-000002",
 "description": "description",
 "dossierType": {
 "id": "1ffa263e-5ef5-4c18-adf0-d8b5a5356fd4",
 "key": "exposedTestDossier",
 "label": "Exposed Test Dossier"
 },
 "createdAt": "2023-04-20T13:59:25.370Z",
 "updatedAt": "2023-04-20T13:59:25.370Z",
 "lastMilestone": {
 "id": "f266bfe9-fa18-4043-ae12-3ebc9a0e752b",
 "key": "Event_1o1ecz1",
 "status": "mail sent",
 "reachedAt": "2023-04-20T13:59:57.230Z"
 },
 "activeTasks": [],
 "_links": {
 "self": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db-5f7e833378f3"
 },
 "tasks": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db5f7e833378f3/tasks"
 },
 "milestones": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db5f7e833378f3/milestones"
 },
 "forms": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db5f7e833378f3/forms"
 },
 "communications": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db5f7e833378f3/communications"
 },
 "attachments": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers/1309819d-d30f-4248-b8db5f7e833378f3/attachments"
 }
 }
 }
 ]
 },
 "_links": {
 "first": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers?page=0&size=1"
 },
 "self": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers?page=0&size=1"
 },
 "next": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers?page=1&size=1"
 },
 "last": {
 "href": "https://librarypreview.skryv.com/exposed/v1/dossiers?page=1&size=1"
 }
 },
 "page": {
 "size": 1,
 "totalElements": 2,
 "totalPages": 2,
 "number": 0
 }
}

Technische beschrijving API-contract

Indien je als developer de technische structuur van de exposed API wil verkennen, is dit mogelijk rechtstreeks in de browser via een Swagger UI. Deze functionaliteit staat standaard uit. Contacteer het Skryv team voor meer informatie.

Dezelfde technische structuur wordt ook in deze sectie van de documentatie beschreven, met toevoeging van functionele informatie en links naar andere relevante pagina’s.

• Klik hier voor overzicht van de verschillende API functies.

• Klik hier voor overzicht van de verschillende API schema’s.

Testen van API-calls

Wie API-calls wil testen en valideren in een gebruiksvriendelijke omgeving kan gebruiken maken van tools zoals Postman.

Voorbeelden van API-calls

Klik hier voor een aantal concreet uitgewerkte voorbeelden.