API's
Endpoints, elke aanmeldmethode, sleutels en scopes, documentatie, testen, versies.
Een endpoint dat een workflow uitvoert
Een API is een basispad met één beveiligingsbeleid; een endpoint koppelt één methode en pad aan één workflow. Wat de afnemer in de body meestuurt, staat in de workflow klaar als {{veld}}; de stap API-antwoord bepaalt de statuscode en wat hij terugkrijgt. U maakt een API met een POST-endpoint, de workflow erachter, en roept hem aan.
Een tabel als API
Niet elk endpoint heeft een workflow nodig. Een tabel publiceert u in één keer als API: lijst (met filters per kolom), één rij ophalen, toevoegen, bijwerken en verwijderen — gewone endpoints die het beleid van de API erven. U kiest welke handelingen u aanbiedt, filtert de lijst met een querystring en voegt een rij toe.
Een endpoint dat doorstuurt naar een verbinding
Met Doorsturen naar verbinding zet u een bestaand systeem achter uw eigen API, zonder workflow ertussen. De afnemer ziet uw adres en uw beveiliging; Flow stuurt de aanvraag door met de sleutel uit de verbinding, die de afnemer nooit ziet. Padparameters zoals {id} gaan mee naar het upstream-pad.
API-sleutels en rechten (scopes)
Een API-sleutel hoort bij een afdeling of team, opent alleen de API's die u aanvinkt, heeft alleen de rechten (scopes) die u noemt en verloopt vanzelf. Een endpoint kan een extra recht eisen. U geeft een sleutel uit zonder dat recht en ziet 403, voegt het toe en ziet 200, en trekt de sleutel in: 401.
Aanmelden met HTTP Basic
Sommige systemen kunnen alleen een gebruikersnaam en wachtwoord meesturen: HTTP Basic. In Flow is dat een client met een client_id en een client_secret, dezelfde als voor OAuth 2.0. U maakt een beveiligingsbeleid met HTTP Basic, hangt het aan een API, maakt een client aan en roept de API aan zoals dat systeem het doet.
Aanmelden met OAuth 2.0 (client credentials)
Applicaties die met elkaar praten, melden zich vaak aan met OAuth 2.0 client credentials: met een client_id en client_secret halen ze bij het token-endpoint een kortlevend token (een uur), en sturen dat mee als bearer-token. De gateway van Flow is zelf die token-uitgever. U maakt een beleid met OAuth 2.0 en een vereist recht, een client met dat recht, haalt een token en roept de API ermee aan.
Een openbare API, zonder aanmelden
Soms mag iedereen iets opvragen: openingstijden, een productcatalogus, een status. Een openbare API staat standaard uit, want elke aanroep hoort herleidbaar te zijn tot een afnemer. Een beheerder zet hem aan voor de werkruimte, met een reden die in het auditlog komt. Daarna opent een beleid Openbaar een API zonder sleutel — en zet de beheerder het weer uit, dan zijn alle openbare API's in één keer dicht.
De beschrijving van een API: OpenAPI en WSDL
Flow beschrijft elke API zelf, uit wat u bouwt: een OpenAPI-beschrijving voor REST en een WSDL voor endpoints die ook SOAP spreken. Standaard leest alleen wie een sleutel of token voor die API heeft de beschrijving. Met Openbare documentatie kan iedereen hem lezen — ontwikkelaars van partners bouwen ertegen zonder account — terwijl aanroepen nog steeds aanmelden vraagt.
API testen: elk endpoint proberen
API testen in de balk links is een werkbank voor al uw endpoints: links de aanvraag en het antwoord, rechts de documentatie die Flow uit het endpoint maakt. U zoekt een endpoint, meldt zich aan zoals een afnemer, voegt queryparameters toe en leest body en headers van het antwoord. Sleutels blijven alleen in het geheugen van uw sessie.
Een nieuwe versie van een API
Wat afnemers gebruiken, verandert u niet onder hun handen. Een nieuwe versie zet u naast de oude: dezelfde naam, versie v2 en een eigen basispad. Een endpoint van v2 kan de logica van v1 hergebruiken via een voorkant — één workflow hoort bij één endpoint, zodat de beveiliging van het ene nooit via het andere lekt. Zijn alle afnemers over, dan zet u v1 uit.
Aanmelden met een webhook-handtekening (HMAC)
Webhooks van betaalproviders, webwinkels en Git-platforms (Stripe, Shopify, GitHub) melden zich niet aan met een sleutel, maar ondertekenen elk bericht: een HMAC over de body met een gedeeld geheim, in een header. Flow rekent die handtekening zelf na. U maakt een beleid met webhook-handtekening en ziet een onondertekend bericht stranden en een ondertekend bericht binnenkomen.