Zo werkt de API van Optifora
Deze pagina beschrijft de vorm van de API: hoe de identiteit wordt aangetoond, hoe versies vooruitgaan, binnen welke grenzen een verzoek blijft, hoe een fout eruitziet en hoe gegevens met de buitenwereld worden uitgewisseld.
Het product is in ontwikkeling en het API-oppervlak wordt nog voltooid. Een naslagdocument voor de eindpunten wordt apart gepubliceerd; deze pagina bevat geen adres en geen voorbeeldaanroep, alleen de werking.
Identiteitscontrole
Elk verzoek behoort toe aan een persoon of aan een geregistreerde toepassing. Een verzoek zonder identiteit dat een beveiligd eindpunt bereikt, komt ongeauthenticeerd terug.
- Toegangsbewijs (bearer)Het toegangsbewijs reist mee in de autorisatiekop van het verzoek. Het is ondertekend en zegt uitsluitend aan wie het verzoek toebehoort.
- Korte levensduurEen toegangsbewijs verloopt na een in minuten gemeten periode; de lengte is een instelling van de installatie en staat standaard op dertig minuten.
- Vernieuwen en wisselenEen sessie wordt verlengd met een vernieuwingsbewijs, en bij elke verlenging wordt een nieuw paar uitgegeven. Wordt een al gebruikt vernieuwingsbewijs een tweede keer aangeboden, dan worden alle sessies van die persoon ingetrokken.
- Bevoegdheden zitten niet in het toegangsbewijs gebakkenHet bewijs draagt alleen de identiteit; wat iemand mag zien, wordt bij elk verzoek aan de database gevraagd. Een ingetrokken bevoegdheid werkt daarom al niet meer voordat het bewijs in handen verloopt.
- Sleutel van de koppelpartijEen geregistreerde toepassing maakt verbinding met een eigen sleutel. De leesbare waarde wordt één keer getoond, bij het aanmaken; opgeslagen worden alleen de hashwaarde en het niet-geheime voorvoegsel waaraan een sleutel te herkennen is.
- De organisatie verleent de toegangHoe breed een toepassing ook wordt gebruikt, zonder een door de organisatie vastgelegde toestemming ziet zij geen enkele regel. De toestemming is gedateerd, afgebakend en intrekbaar.
Versiebeheer
- De versie zit in het padEindpunten worden achter een versievoorvoegsel gepubliceerd; het oppervlak van vandaag is versie één.
- Een brekende wijziging opent een nieuw padDe afspraak van een bestaand eindpunt wordt niet ter plekke gebroken. Een niet-verenigbare wijziging wordt op een nieuw versiepad gepubliceerd terwijl het oude blijft werken.
- Het document noemt zijn eigen versieHet naslagwerk draagt het versienummer waaruit het is opgebouwd; welke versie u leest, wordt door het document zelf beantwoord.
Omgevingen en grenzen
Het naslagwerk benoemt twee omgevingen: productie en lokale ontwikkeling. Het hoofdadres wordt samen met de sleutel aan een koppelpartij overhandigd; het wordt niet op deze pagina gepubliceerd.
- Draaien en gereedheid worden apart gemetenEén eindpunt zegt dat het proces draait; het tweede stuurt een echte vraag naar de database en bevestigt dat die bereikbaar is. Alleen het tweede bepaalt of er verkeer naartoe mag.
- Browserherkomsten zijn tot een lijst beperktVerzoeken van een andere herkomst worden alleen aanvaard vanaf vooraf opgegeven herkomsten; zolang die lijst leeg is, wordt een browserverzoek van een andere herkomst geweigerd.
- Limiet op de inhoudDe inhoud van een verzoek mag niet groter zijn dan vijf megabyte. Grote verzamelingen reizen als een bulkoverdrachtstaak met een eigen statusregistratie, niet als één verzoek.
- Geheimen worden niet in het logboek geschrevenHet serverlogboek bewaart geen autorisatiekop, geen cookie, geen wachtwoord en geen burgerservicenummer.
Snelheidslimiet
De limiet geldt per adres en per minuut. De standaard is 120 verzoeken per minuut en wordt bij de installatie ingesteld. Wat er overblijft, wordt bij elk antwoord in de kopregels gemeld.
| Antwoordkop | Wat het zegt |
|---|---|
| x-ratelimit-limit | Het totale tegoed binnen het tijdvenster. |
| x-ratelimit-remaining | Wat er in dit tijdvenster nog over is. |
| x-ratelimit-reset | Seconden totdat het tegoed wordt vernieuwd. |
| retry-after | Hoeveel seconden vóór een nieuwe poging. Alleen aanwezig op het antwoord dat het verzoek heeft geweigerd. |
Zodra de limiet is overschreden, wordt het verzoek geweigerd en vertelt het antwoord hoeveel seconden u moet wachten. Een nieuwe poging volgt ná die tijd, niet meteen.
Foutopmaak
Elke fout komt in dezelfde envelop terug: een kort codeveld waarop de machine kan vertakken, en een uitlegveld dat een mens kan lezen.
- errorDe korte code waarop de cliëntzijde haar keuze baseert.
- messageDe uitleg van wat er is gebeurd.
| Status | Codeveld | Wat het betekent |
|---|---|---|
| 400 | Bad Request | Het verzoek komt niet overeen met het schema. De toelichting noemt het veld dat ontbreekt of ongeldig is. |
| 401 | unauthenticated | Er is geen geldige identiteit: er is geen bewijs meegestuurd, het is verlopen, of het kon niet worden geverifieerd. |
| 404 | Not Found | Geen zodanig eindpunt, of geen zodanige registratie. |
| 429 | Too Many Requests | De snelheidslimiet is overschreden; het antwoord vertelt hoelang u moet wachten. |
| 5xx | internal_error | Een onverwachte storing. De details worden niet aan de cliëntzijde gegeven; ze worden naar het serverlogboek geschreven. |
Paginering
Eindpunten die lijsten teruggeven, nemen dezelfde twee parameters aan en geven dezelfde tellers terug, zodat een bladerende cliëntzijde niet voor elk eindpunt opnieuw wordt geschreven.
- limitHoeveel registraties een pagina moet bevatten. Ten minste één, ten hoogste tweehonderd; vijftig als er niets is ingesteld.
- offsetHoeveel registraties worden overgeslagen. Begint bij nul.
- totalHoeveel registraties in totaal aan de filters voldoen.
- countHoeveel registraties dit antwoord daadwerkelijk draagt.
Het antwoord herhaalt ook de gebruikte limit en offset; de cliëntzijde leest haar positie uit het antwoord in plaats van die te raden.
Gegevensuitwisseling en webhooks
De uitwisselingswijze is een instelling, geen apart product: elke geregistreerde toepassing draagt op haar eigen registratie de wijze waarin zij werkt.
| Wijze | Wat het betekent |
|---|---|
| Eén richting — naar buiten | Optifora publiceert gegevens; de andere kant leest ze of neemt een abonnement op gebeurtenissen. |
| Eén richting — naar binnen | De andere kant stuurt gegevens door; Optifora controleert ze en schrijft ze weg. |
| Tweerichtingsverkeer | Beide kanten schrijven; de regel bij tegenstrijdigheid wordt vooraf vastgelegd. |
| Handdruk | Elke overdracht opent een sessie: aanbod, verificatie, goedkeuring, overdracht en ontvangstbewijs. Het ontvangstbewijs blijft bij beide kanten. |
- Gebeurtenissen worden naar buiten geduwdEen webhook stuurt de gebeurtenis naar het terugkoppeladres dat de geregistreerde toepassing heeft opgegeven. Een gebeurtenis die niet kan worden bezorgd, blijft in de wachtrij staan en wordt opnieuw geprobeerd; ze wordt nooit stilzwijgend weggegooid.
- Hetzelfde verzoek schrijft niet twee keerEen schrijfverzoek draagt een sleutel voor eenmaligheid. Een tweede verzoek met dezelfde sleutel maakt geen tweede registratie aan.
- Elke aanroep wordt gemetenWie heeft aangeroepen, wanneer, met welke reikwijdte en met welk resultaat — het wordt allemaal vastgelegd. Diezelfde registratie beantwoordt zowel het zoeken naar fouten als de vraag wie deze gegevens heeft opgehaald.
- Onze eigen toepassingen gebruiken dezelfde deurEr bestaat geen bevoorrecht tweede pad. Onze eigen koppeling is het bewijs van het oppervlak dat een ontwikkelaar van buiten aantreft.
Het gegevensmodel voor de uitwisselingslaag ligt er; de eindpunten ervan zijn nog niet gepubliceerd. Zodra dat gebeurt, verwijst dit onderdeel naar hun vermeldingen in het naslagwerk.
Naslagdocumenten
Het naslagwerk wordt niet met de hand geschreven; het wordt opgebouwd uit de schema's van de eindpunten. Naarmate elk eindpunt zijn schema overdraagt, vult het document zichzelf, zodat het document en het gedrag niet uiteen kunnen lopen.
- Vandaag: in voorbereidingDe schema's verhuizen module voor module. Voordat het document wordt gepubliceerd, zullen het verzoek en het antwoord van elk eindpunt daarin zichtbaar zijn.
- Er worden twee vormen gepubliceerdEen machineleesbaar OpenAPI-document, en een naslagpagina die uit datzelfde document wordt opgebouwd en in een browser te doorbladeren is.
- De toegang kent lagenHet overzicht staat voor iedereen open. Het volledige naslagwerk kan achter een documentatiebewijs zitten dat aan een geregistreerde koppelpartij wordt gegeven; productiesleutels en terugkoppeladressen zijn helemaal geen documentatiekwestie — die horen bij de registratie van de toepassing.
- AdresstandaardEr worden twee naslagwerken gepubliceerd en hun adressen liggen vast: client-api.optifora.com/docs is open, admin-api.optifora.com/docs vereist een bevoegdheid en is naar buiten toe gesloten. Geen van beide is vandaag al in de lucht; de koppelingen worden in dit onderdeel toegevoegd zodra dat wel zo is.
Is uw koppelplan al duidelijk, schrijf ons dan via de contactpagina: u hoort als een van de eersten wanneer het oppervlak opengaat.
Hebt u een bepaald verzoek?
Deze pagina's leggen uit hoe het ondersteuningsproces werkt. Hebt u een verzoek of een vraag, schrijf ons dan vanaf de contactpagina.
Ga naar de contactpagina