Eeste iteratie voor de API-documentatie beschikbaar.

Dit is een statische kopie van het eerdere discussie.kinggemeenten.nl.
Nieuwe discussies kunnen in de GitHub repository 'StUF standaarden' als issue worden opgevoerd.

9 reacties / 0 nieuw
Login of registreer om te kunnen reageren
vr, 15-12-2017 - 14.04u
#1
Johan Boer
Eeste iteratie voor de API-documentatie beschikbaar.

Op swaggerhub is de eerste versie van de documentatie van de API voor Open RaadsInformatie beschikbaar.

https://swaggerhub.com/apis/King4/Open-Raadsinformatie-v01/1.0.0

De documentatie is opgesteld volgens OpenAPI v3.0.0. Er zitten nog wat schoonheidsfoutjes in, met name de manier waarop de links gedefinieerd zijn. Dat pak ik in de komende iteratie op. 

Ik wil aan alle betrokkenen vragen om input te leveren om de kwaliteit en gewenste functionaliteit te kunnen bewerkstelligen. Het is prettig als deze input, verbetervoorstellen etc. via dit discussieplatform worden ingediend en eventueel wordt bediscussieerd. 

 

Bovenaan
Joeri Bekker

Ik ben zelf niet bekend met dit koppelvlak of het datamodel maar ik juich de OpenAPI richting die hier wordt gekozen toe!

Is er bewust afgeweken van (of niet gekeken naar) de URI strategie zoals die in DSO staat (URI-15 en URI-23)?

Bovenaan
Εelcο Ηοtting

Mooi initiatief!

Toen ik dit via Google probeerde terug te vinden vond ik ook dit: http://docs.openraadsinformatie.nl  - met exact dezelfde naam. Zijn de betrokkenen van die API ook betrokken? 

Waar is het informatiemodel te vinden?

Bovenaan
Johan Boer

Er is zeker niet bewust afgeweken van de URI-strategie van DSO. Sterker nog, we willen ons zoveel mogelijk conformeren aan deze strategie. Wij hebben nog niet zoveel ervaring met deze strategie en met reacties zoals deze gaan we dan ook het koppelvlak conform de DSO-strategie te krijgen. Dank voor het meedenken en ik ga me verdiepen in punten 15 en 23. 

Bovenaan
Johan Boer

Het informatiemodel dat ten grondslag ligt aan deze API is eerder aangeboden te consultatie. De discussie waar de zip ter beschikking wordt gesteld is te vinden op :

https://vng-realisatie.github.io/StUF-Standaarden/discussie/gemma/koppelvlak-open-raadsinformatie/concept-informatiemodel-open-raadsinformatie-ter

Bovenaan
Joep Meindertsma

Ziet er goed uit! Ik heb nog een aantal opmerkingen. Sommigen hiervan zullen mogelijk al genoemd zijn in andere threads.

  1. AN10 als identificatie lijkt mij iets te beperkend. Ook URLS, die doorgaans een stuk langer zijn, zouden mogelijk (of liever nog: verplicht) moeten zijn. URL's als ID's gebruiken zorgt dat de data direct meer als linked data te beschouwen is.
  2. AN200 voor amendementen is waarschijnlijk te kort. Daarnaast is het mogelijk handig om direct een format als markdown te vragen wanneer er opmaak wordt toegevoegd.
  3. HAL is een mooie standaard, maar is helaas niet geschikt voor linked data en vereist bij veel RESTful JSON API’s relatief veel aanpassingen om compliant te worden. Persoonlijk vind ik JSON-LD daarom een meer geschikte kandidaat. Om acties en pagination af te handelen zou HYDRA kunnen worden toegevoegd.
  4. Het implementeren van query parameters en zoekopdrachten eisen mogelijk vrij veel van  RIS developers.
  5. De specificatie staat volledig in het Nederlands beschreven. Dat is begrijpelijk, maar het maakt internationale koppeling wat lastiger. Zeker een mapping naar Popolo (en de W3C OpenGov ontologie) zou erg mooi zijn om mogelijk te maken.
  6. Datums en tijden noteren volgens de ISO 8601 standaard is handiger dan de NL notatie aanhouden, aangezien dit door vrijwel alle libraries wordt ondersteund.
  7. Momenteel is er nog geen endpoint voor individuele resources, maar moet deze met ene query parameter worden gevonden, bijvoorbeeld: gemeente.nl/moties?motieIdentificatie=415
    Het is conventie en meer RESTful om de losse resources opvraagbaar te maken op adressen zoals: gemeente.nl/moties/415
Bovenaan
Joeri Bekker

3. HAL is een mooie standaard, maar is helaas niet geschikt voor linked data

Volgens mij is HAL juist gemaakt voor linked data. De H staat voor Hyperlinked en de standaard voegt overal het "_links" veld toe om aan te geven dat er linked data is. Kan je aangeven waarom je denkt dat HAL hiervoor niet geschikt is?

7. Momenteel is er nog geen endpoint voor individuele resources, maar moet deze met ene query parameter worden gevonden, bijvoorbeeld: gemeente.nl/moties?motieIdentificatie=415
Het is conventie en meer RESTful om de losse resources opvraagbaar te maken op adressen zoals: gemeente.nl/moties/415

Dit lijkt me inderdaad een vereiste van een degelijke RESTful API.

Bovenaan
Nanning Buitenhuis

1. "URL's als ID's gebruiken zorgt dat de data direct meer als linked data te beschouwen is."

URL's als Id is denk ik af te raden, aangezien het niet te verwachten is dat alle URLs valide blijven over de verwachte levensduur van OpenRaadsinformatie. Hoeveel gemeentes zijn al veranderd van leverancier in de afgelopen 10 jaar en zijn de oude Ris systemen nog in de lucht? Ook is crosslinken moeilijker: de equality erg moeilijk vast te stellen (is http://foo/bar?x=y gelijk aan https://foo/bar/ )

7.

Entiteiten direct kunnen benaderen heeft qua ontsluiten voordelen.

Bovenaan
Breyten Ernsting

Ik ben het eens met Joep's punten, m.n. die over HAL. Waarom niet iets als JSON-LD?

 

Wat ik voorderest nog mis zijn manieren om te sorteren. Dit is met name belangrijk in een situatie waar ik "bij wil blijven" met de inhoud. Of is er altijd 1 manier om te sorteren?

Bovenaan