search

Geonovum / KP-APIs

26 stars 40 forks source link

6.1.12 moet geschrapt worden! #251

Closed ajslaghu closed 3 years ago

ajslaghu commented 5 years ago

6.1.12 API-12: API's zijn bij voorkeur alleen bruikbaar met behulp van een API-key

Voor alle API's wordt bij voorkeur minimaal een registratie inclusief acceptatie van de fair use voorwaarden vereist. Op basis hiervan zal dan een API-key wordt uitgegeven.

Dit is een punt dat geschrapt moet worden, of omgekeerd. Er moet zakelijke reden zijn, alvorens Api keys noodzakelijk gesteld worden.

jasperroes commented 5 years ago

Kun je toelichten waarom deze omgedraaid zou moeten worden? Tot nu toe krijg ik van bijna alle gebruikers van onze API’s te horen dat ze het gebruik van een API key logisch vinden omdat dit de mogelijkheid biedt om service te verlenen.

Registratie kan in mijn ogen heel simpel: alleen een e-mailadres invoeren waarna de API key wordt verstuurd en fair use voorwaarden accepteren.

Doe je niets met toegang dan kun je in mijn ogen als aanbieder niet eens fair use voorwaarden aanbieden omdat je geen echte manier hebt om dit te garanderen voor alle fair use gebruikers

ajslaghu commented 5 years ago

In het geval van Open data is het ongewenst. Open data is niet enkel een keuze , maar ook een wettelijke plicht. Zie hiervoor de Who, PSI, en de aanstaande Woo.

Indien je dan data beschikbaar stelt vanuit het oogpunt om aan je 'open data verplichtingen' te voldoen, zou deze aan de normen die hiervoor opgesteld zijn voldoen: Wat is open data?

Open data is informatie die volgens de definitie van de Rijksoverheid voldoet aan de volgende criteria:

de data zijn openbaar;
de informatie is minimaal herbruikbaar onder een open licentie;
de data zijn bekostigd uit publieke middelen, beschikbaar gesteld voor de uitvoering van die taak;
de data voldoen bij voorkeur aan open standaarden (geen barrières voor het gebruik door ICT-gebruikers of door ICT-aanbieders);
open data is bij voorkeur computer-leesbaar, zodat zoekmachines informatie in documenten kunnen vinden.
  1. Er is juridisch geen sprake van openbaarheid als er een api key aangevraagd moet worden, hoe licht dat proces ook is.
  2. een api is niet 100% voor computers toegankelijk als er een mens aan te pas moet komen voor de registratie van een API key.
  3. In principe geld vanuit de Woo dat de overheid niet hoeft te weten waarvoor de gegevens gebruikt worden. Het principe van een unieke identificatie staat hier haaks op.
  4. Vanuit concurrentieoverwegingen (bij hergebruikers) kan het ongewenst zijn dat de overheid op individueel niveau data gebruik kan volgen. Wellicht wordt een algoritme of geheime use case hiermee onthuld.

Zie ook mijn publicatie hierover: https://openstate.eu/en/2014/03/open-data-stop-making-a-mess-of-it/

De afgelopen jaren heb ik zelf meer ervaring met Linked Data opgedaan. Voor mijn gevoel wordt er vaak voor te zware implementaties gepleit, maar het beschikbaar stellen van data onder een publieke link op basis van een http response in JSON xhtml of XML (het liefst in een simpele schema standaard) is zeer krachtig. Juist postcodes, gemeenten, straatnamen in gemeenten, adressen, regio indelingen zoals provincies of andere varianten, zijn er gebaat bij open en vrij toegankelijk te zijn.

In het geval van shared data (dus onder specifieke licentie, in vertrouwen tussen 2 partijen, zoals 2 gemeenten) zou ik authenticatie en authorisatie van harte aanbevelen.

Wel dan afsluitend het capaciteitsprobleem. Ik begrijp dat onbeperkt dingen weggeven zonder 'overeenkomst' en sanctioneringsmogelijkheid (afsluiten) niet goed voelt. Misbruik ligt op de loer.

In de praktijk heeft de overheid de vrijheid om misbruik te voorkomen door maatregelen te nemen, als het gaat om het beschermen van de dienst naar anderen. Bij een moderne website is dit de normaalste zaak van de wereld. Via online proxys worden abusers en DoS aanvallen tegengehouden. Via logging files worden 'anonieme' abusers geïdentificeerd en geblokkeerd, met verschillende strategieen er om heen. Funda toont een captcha als het ip adres van de afzender verdacht is. Ratelimitting kan op ip adres niveau, maar ook op landsniveau om niet traceerbaar misbruikvanuit het buitenland te beperken. In de praktijk is de grootste oorzaak van misbruik een slechte inrichting van een API, waarbij veelal bulkgebruik niet goed gefaciliteerd wordt.

Tegelijkertijd snap ik dat er behoefte is om tussen overheden diensten te garanderen. Daarom is het (wellicht een bestpractice) om tevens open & shared data via een geauthenticeerde gateway aan te bieden, en die vanuit een andere service capaciteit te leveren.

--> Open data zonder authenticatie qua service as is, met risico beperkende maatregelen. --> trusted parties krijgen Shared en open data via service levels en FUP's.

dvh commented 5 years ago

Volgens mij zijn "open data" en "API strategie" twee compleet verschillende discussies. Een API is een (van de) service (s) om, in sommige maar lang niet alle gevallen, data te kunnen bevragen. In de meeste usecases gaat het in deze context bovendien over "gesloten" data, dankzij de hele privacy discussie (ik wil precies weten welke applicatie/organisatie mijn data wil inzien/hebben) waardoor het noodzakelijk is om de vragende applicatie te kunnen identificeren.

Als we dan wél kijken naar de Open Data discussie: de BAG is beschikbaar als Open Data omdat het ontsloten wordt via (o.a.) Linked Data. De BAG API daarentegen, is een extra service die een specifieke doelgroep bedient met het idee om deze te kunnen integreren in applicaties. Het compleet anoniem laten benaderen van een API is nooit een goed idee, en als bovendien niemand er een probleem mee heeft om laagdrempelig een API key aan te vragen om zijn/haar applicatie te laten communiceren met een (gratis!!) service, dan vind ik het een 100% best practice richting API providers om tenminste een API key te gebruiken. Sterker nog: ik zou het slecht advies vinden om dit niet te doen, enkel vanwege de "open data principes."

frisopenninga commented 5 years ago

Open data beleid is iets anders dan open service beleid. Dat eerste hebben we (en is verouderd), dat laatste niet.

En API keys mogen van mij verplicht worden in dat laatste, als BZK dat gaat ontwikkelen. Want een overheid die zijn gebruikers niet wil kennen (en dus niet wil servicen), is volgens mij niet de digitale overheid die we voor ogen hebben. Hoewel er nog geen open service beleid is, proef ik bij beleidsmakers nu vaker de opvatting dat de open data verplichting afgedekt wordt door een datadump (het ouderwetse 'over de schutting heen gooien'). De huidige ambities van de digitale overheid vragen om meer dienstverlening en daar mag best iets tegenover staan (een API key aanvraag, maar misschien zelfs wel een (betaalde) SLA...)

ajslaghu commented 5 years ago

Ik ben het met Friso eens dat het huidige leveringsniveau van open data (over de schutting) te wensen overlaat. Een kwaliteitsslag is zeker gewenst en de levering via API's in plaats van statische bestanden is dan ook voor veel waardevolle data de weg vooruit.

De opmerking van Dvh gaat volgens mij over de stelling in welke mate open data onderdeel zouden moeten zijn van een api strategie. Prima als open data uitgesloten worden, noem het dan 'api strategie voor shared data en transacties'. Dan is er ook ruimte voor open data om met een eigen API strategie te komen... Maar volgens mij is dat ook niet gewenst.

Overigens: Pittige discussie maar op het stuk heb ik verder geen enkele opmerking. Ik denk dat ook open data een stap vooruit komt met deze apistrategie, maar dat clausule 6.1.12 genuanceerd moet worden. Is het een idee om daar samen aan te schrijven?

frisopenninga commented 5 years ago

Uit nieuwsgierigheid: waarop baseer je de stelling dat er bij een API key juridisch geen sprake is van openbaarheid?

Ik ben absoluut geen jurist, maar ken uit wet- en regelgeving rond open data geen dergelijke concrete regels. Veel technischer dan "voor zover mogelijk langs elektronische weg, in een open en machinaal leesbaar formaat, samen met de metadata, waarbij het formaat en de metadata voor zover mogelijk voldoen aan formele open standaarden" in de WHO wordt het niet, voor zover ik kan vinden.

jasperroes commented 5 years ago

Ja, inderdaad pittige discussie, maar het geeft volgens mij wel goed mee waar de verschillen in de opvattingen zitten. Het lijkt mij heel goed om hier samen aan te schrijven waarbij we dan de nuance die ook in deze discussie zit mee moeten nemen. Zou jij een eerste aanzet willen doen?

ajslaghu commented 5 years ago

Er is jurisprudentie over de definitie van openbaarheid. Wanneer is dit wel en niet het geval. In de digitale zin daar ook al het een en ander over gezegd is. Zo zijn er diverse zaken geweest rond video op het web bij het Europese hof waarbij definities hier werden gehanteerd. (dit ging over ip blocking in relatie tot openbaarmaking).

Openbaarmaking is een daad van het algemeen bekend maken, het toegankelijk voor iedereen maken, niet inzage geven op een specifiek verzoek (van een individu). https://www.encyclo.nl/begrip/openbaarmaking

tomkunzler commented 5 years ago

Ik ben het eens met Lex hierboven dat als het gaat om open data die via een API gedeeld wordt dat vrije toegang tot de API zonder registratie over een API-key de voorkeur verdient (dat zou de default voor open data moeten zijn). Dit is conform de open data definitie van de Rijksoverheid die te vinden is via data.overheid.nl. Gaat nog lang niet altijd goed want bij de Tweede Kamer werken ze bijv. voor het open data portaal met een IP-Whitelist (dan liever een API-Key).

Wellicht dan voor de algemene API-strategie (dus niet perse open data) wel iets aangeven dat het wenselijk is dat de registratie om een API-key te krijgen geautomatiseerd en snel verloopt. Bij TenderNed moet je bijvoorbeeld een formulier uitprinten met verzoek om toegang met motivatie en handtekening. En die weer inscannen en dan een flinke poos wachten op toegang.

Je kan in mijn ogen dus differentieren (nuance toevoegen):

Hartelijke groet, Tom Kunzler Open State Foundation

dvh commented 5 years ago

Ik ben het eens met Lex hierboven dat als het gaat om open data die via een API gedeeld wordt dat vrije toegang tot de API zonder registratie over een API-key de voorkeur verdient (dat zou de default voor open data moeten zijn).

Wat mij betreft:

Ik ben het eens met Lex hierboven dat als het gaat om open data die ALLEEN via een API gedeeld wordt dat vrije toegang tot de API zonder registratie over een API-key de voorkeur verdient (dat zou de default voor open data moeten zijn).

Dat zouden we in de API strategie als een "LET OP" kunnen opnemen, als in:

LET OP: Als de API open data ontsluit en deze API de enige manier is om de open data te verkrijgen doe je er goed aan om óf geen API key te vragen óf een andere manier ernaast te zetten om de data zonder beperkingen te kunnen bemachtigen.

joepio commented 5 years ago

Een API sleutel vereisen schept een onnodig hoge barrière, beperkt herbruikbaarheid en maakt linked open data praktisch onmogelijk (en dat is zonde, want linked data is gaaf).

Als je een API back-end wil beschermen tegen spam of anderzijds grote hoeveelheden requests, gebruik je rate limiting: IP adressen die een X aantal verzoeken in een Y aantal seconden plaatsen, geef je een 429 terug. Een API key verplicht je pas als volgende laag aan bescherming: wanneer iemand meer dan X per Y aantal requests wil doen.

siccovansas commented 5 years ago

Goed punt @joepio. Wat zijn eigenlijk expliciet alle redenen om een API key/registratie te gebruiken?

Overigens zie ik in 6.2.2 dit staan (bold heb ik toegevoegd):

Open API's: voor ontsluiten van diensten zonder toegangsbeperking bv open data.

Gesloten API's: voor ontsluiten van diensten met toegangsbeperking bv persoonsgegevens en vertrouwelijke gegevens of diensten voor specifieke partijen.

Zijn er nog meer punten in de API strategie die wellicht teveel vanuit een Gesloten API perspectief zijn bekeken ipv van een Open API perspectief?

jasperroes commented 5 years ago

Wat betreft Linked (Open) Data: dat is inderdaad gaaf en de API strategie legt daar ook geen enkele belemmering in op, de API strategie is namelijk geschreven voor Rest API’s en dat is wat mij betreft niet direct een logische ontsluitingsroute voor Linked Data. Vanuit mijn Kadaster perspectief rondom het dataplatform waar ik aan mag werken beiden we zowel Linked Data aan (via een open sparql endpoint) als rest api’s. Beiden beiden we als Kadaster aan als extra mogelijkheden om de data te kunnen bevragen naast alle geo-services en downloads. Met alle andere mogelijkheden voldoen we ruimschoots aan het open data beleid, al het andere is dus primair extra service richting onze afnemers.

Voor het sparql endpoint geldt een fair use policy en we geven geen garanties over de beschikbaarheid (dat is technisch erg complex als je je database vrij laat bevragen). Hierop kun je dus ook geen betere SLA afsluiten, ondanks dat we hier al wel vragen naar krijgen vanuit commerciële organisaties die vaak meer zekerheid willen dan een fair use policy. Aan de rest api kant kiezen we er nu bewust voor om api keys toe te passen om daarmee meer service te kunnen bieden. We kiezen er daarbij voor om een minimum aan informatie te vragen (we hebben alleen een emailadres nodig om je de api key te kunnen mailen). Bij het verstrekken van de key vragen we of we je op de hoogte mogen houden van wijzigingen in de api, krijgen we daar geen antwoord op dan zullen we het emailadres alleen gebruiken als we een gebruiker af moeten sluiten ivm niet voldoen aan policy). Daarnaast zien we dat het gebruik van de API flink toeneemt en dat we ook hier vragen krijgen over een betere SLA. Die kunnen we nu niet beiden omdat de kosten daarvan door niemand gedragen worden. Als partijen echter bereid zijn te betalen voor de additionele SLA en daarmee service zien we daar wel wel mogelijkheden voor waarbij we uiteraard alleen zelf kostendekkend willen zijn. Wij kiezen er daarom nu bewust voor om nu al met API keys te werken voor de additionele services die we bieden om daarmee in de toekomst nog meer service te kunnen beiden.

API keys zijn verder wat ons betreft ook een veel betere manier om toegang te verlenen dan dit op IP adres uit te voeren omdat de gebruiker lang niet altijd vanaf 1 IP adres komt en er vaak ook meerder gebruikers achter 1 IP adres kunnen zitten. We sluiten dan dus mogelijk veel te veel gebruikers af, of juist veel te weinig waarmee we alle andere gebruikers duperen.

Wij gebruiken de API key bewust niet om te loggen welke data er opgevraagd wordt, maar wel om te kijken hoe de API gebruikt wordt zodat we daarmee de API en de door ons geleverde service kunnen verbeteren voor de gebruiker.

We streven er trouwens na om de API key aanvraag heel simpel te maken: e-mailadres invullen en API selecteren en na indienen binnen een minuut een mail met de key. En ja, voor een computer werkt dat niet, maar daar mikken we met de rest api’s ook niet op, wij gaan ervan uit dat er altijd een developer betrokken is bij de implementatie.

jasperroes commented 5 years ago

Voorstel werkgroep: we voegen bij het principe rondom de API-key een waarschuwing toe dat als open data alleen maar via een API wordt aangeboden dat je dan moet kijken of je wel aan de open data principes voldoet.

ajslaghu commented 5 years ago

Wat betreft Linked Open Data, SPARQL is een voorbeeld van hoe deze aangeboden kan worden maar tegelijkertijd de meest complexe en verregaande wat betreft dienstverlening. Immers complexe vragenstukken kunnen via een SPARQL endpoint beantwoord worden. Er is sprake van 'compute'.

Andere vormen van Linked Open Data , zoals xml/rdfa, json-ld bieden enkel een 'pagina', en geen slimme queries. Hiermee wordt de complexiteit van SPARQL api's effectief omzeild. Webservers zijn middels memcaching in staat om extreem zwaar gebruik makkelijk te faciliteren. http://data.bibliotheken.nl/ is een mooi voorbeeld hiervan (er is ook een SPARQL api trouwens).

Vanuit Europa komt er wetgeving aan die overheden verplicht om open data via realtime API's aan te bieden, waar relevant: https://ec.europa.eu/digital-single-market/en/proposal-revision-public-sector-information-psi-directive

Voorstel: Waar we naar op zoek moeten is een werkwijze waarbij open data via api's mogelijkerwijs apikeyless is te gebruiken (maar wellicht ook met apikey), en waarbij de data die niet open is (vanwege transactionele eigenschappen als schrijven, shared data / keteninformatie ) wel met een apikey werkt.

6.1.12 API-12: API's authoriseren gebruik van de API met behulp van een API-key

Voor alle API's waarbij gebruik geauthoriseerd dient te worden wordt bij voorkeur minimaal een registratie inclusief acceptatie van de fair use voorwaarden vereist. Op basis hiervan zal dan een API-key wordt uitgegeven.

! Let op: voor open data mag er geen authorisatie verplicht gesteld worden. Oneigenlijk gebruik kan via diverse maatregelen ontmoedigt en voorkomen worden.

ehotting commented 5 years ago

API-key is een mogelijkheid om requests aan een afnemer te koppelen, er zijn ook andere methoden. Waarom dit überhaupt zo specifiek voor willen schrijven? Wat gaat mis als dit hele artikel achterwege blijft?

ehotting commented 5 years ago

(Ik probeer de API strategie aan hard core developers te laten lezen maar die haken af met een TL;DR )

jasperroes commented 5 years ago

Wat betreft Linked Data: de optie via een URI bieden wij ook, de eindgebruiker heeft dan echter wel heel weinig invloed op welke data hij krijgt. Voor het Kennisplatform is dit echter buiten scope omdat we ons nu alleen op REST API's richten.

@ehotting Op zich gaat er niets mis als we deze paragraaf niet opnemen, echter is er dan wel een kans dat iedere partij die iets met autorisatie wil doen dit op een andere manier doet. Dat maakt voor developers het gebruik van de API's niet eenduidiger en makkelijker. En als ik je redenatie volgt kunnen we eigenlijk alles wel weglaten, er is altijd wel een andere methode om hetzelfde te bereiken ;-).

@ehotting Voor de hardcore developers is er de bijlage met een overzicht van de API principes, dat is maar iets meer dan 1 kantje. Je mist dan wel alle andere hoofdstukken.

ajslaghu commented 5 years ago

@jasperroes je punt over authorisatie begrijp ik niet helemaal.

Met een voorbeeld: Als ik bij gevoelige (bijvoorbeeld mijn eigen belasting) gegevens zou willen dan heb ik hiervoor authorisatie nodig die ik kan delen / invoeren via de app (via een Oauth token naar ik meen). Ik mag aannemen dat een app die juist authoriseert valide in gebruik is. Indien er misbruik plaatst vindt, kan de gebruiker geblokkeerd worden vanwege het gebruik van een app die niet werkt. ("Uw authorisatie token xyq is geblokkeerd vanwege misbruik. neem contact op met uw appmaker, en/of trek de token in via ...")

Er is bij Oauth technische geen noodzakelijke behoefte aan aanvullende apikeys ten behoeve van het tegengaan van abuse van appmakers.

Indien er geen Oauth nodig is, zou er api keyless gewerkt moeten kunnen worden, c.f. eerdere discussie. Ergo, apikeys als authorisatie is eigenlijk niet nodig. Het artikel kan integraal vervallen.

--> Kan iemand in deze redenering nog gaten schieten.

ehotting commented 5 years ago

Ergo, apikeys als authorisatie is eigenlijk niet nodig. Het artikel kan integraal vervallen.

@jasperroes @ajslaghu Dit is precies wat ik bedoel. Wat nodig is, is sterk afhankelijk van de specifieke use case. Of je met JWT tokens, OAuth, misschien NLX, mutual TLS, helemaal niks (Extreme Open Data ;) ) heeft direct invloed op of je wel / niet iets hebt aan API keys of dat het alleen maar in de weg zit. Ik heb bij dit artikel de idee dat teveel wordt geredeneerd vanuit de voorkeur van een organisatie. Hooguit zou ik iets op willen nemen over het snel toegankelijk maken van testomgevingen. Daarbij kan het voorschrijven van API keys mogelijk helpen.

jasperroes commented 5 years ago

Voor autorisatie deel ik jullie conclusie, ik bedoelde echter authenticatie. Dat kan ook op verschillende manieren, maar api-keys zijn daar wellicht wel een logische oplossing. Wat mij betreft is het ook prima om het hele principe weg te laten.

HenriKorver commented 5 years ago

Hooguit zou ik iets op willen nemen over het snel toegankelijk maken van testomgevingen. Daarbij kan het voorschrijven van API keys mogelijk helpen.

@ehotting Interessant, maar zou je hier iets specifieker over kunnen zijn?

ehotting commented 5 years ago

zou je hier iets specifieker over kunnen zijn?

Wanneer je nu een API op het oog hebt die zware toegangsmaatregelen kent, kost het veel effort om met de API te spelen. Aan te bevelen zou zijn om een test- of desnoods demo-API te maken met dezelfde specificatie, dummy-gegevens en slechts een API key - ipv bijv. een hele Digikoppeling procedure of iets waar je voor moet betalen. Zodat je binnen een paar minuten wat kunt testen en vaststellen of de API idd nuttig is voor het doel waar je hem voor wilt gebruiken.

HenriKorver commented 5 years ago

Bedankt, nu is het duidelijk. Je bedoelt hier met testomgeving zoiets als een sandbox, playground of demo-versie van de API waar de potentiële gebruiker met de API kan spelen om te kijken of het wat is, dus eigenlijk een speelomgeving. Dat is wat anders dan een testomgeving waarin je wilt aantonen dat je compliant bent met een API. Daar zal namelijk wel gecheckt moeten worden of de consumer kan voldoen aan de zware beveiligingsmaaatregelen.

jasperroes commented 4 years ago

Besluit van werkgroep vereist, API-key is inmiddels ook minder expliciet in de API strategie opgenomen.