Subsidieregister API documenteren in OAS

Overig
#1

Misschien een beetje ‘off topic’ (want geen geo…) maar ik post mijn vraag toch maar hier, omdat de Open API Specification (OAS) ook gebruikt wordt voor het documenteren van de REST API’s van PDOK.

Een paar maanden geleden heeft de provincie Zuid-Holland de website https://subsidieregister.zuid-holland.nl in de lucht gebracht. Voor het ophalen van de gegevens uit de achterliggende database is een API ontwikkeld. Die API ben ik nu aan het documenteren met behulp van SwaggerHub. Voor mij de eerste keer dat ik zoiets doe. Zie Build, Collaborate & Integrate APIs | SwaggerHub

Mijn eerste vraag is: Is SwaggerHub handig? Wat is naar jullie idee de beste tooling?

Mijn tweede vraag is inhoudelijk en betreft de response op dit request:
https://subsidieregister.zuid-holland.nl/api/jaarbedragen

Het request geeft een JSON-array terug. Hoe geef ik dat aan in OAS? Wat ik nu heb, is volgens mij fout.

screenshot2
screenshot2800×451 42.3 KB

screenshot1
screenshot1809×273 25.2 KB

1 like
#2

Het array deel van de vraag kan ik wel beantwoorden met een linkje naar Data Types . De Arrays sectie zou voldoende informatie moeten bevatten om je specificatie te corrigeren.

2 likes
#3

Dankjewel voor de tip!

#4

@FrieseWoudloper ik typ het meestal direct in editor.swagger.io, mocht je op zoek zijn naar een GUI dan is deze wel fancy: https://www.apicur.io

#5

Dankjewel voor je suggesties @dvh!

De eerste versie van de documentatie van de subsidieregister API van Zuid-Holland staat inmiddels online. Feedback is van harte welkom: https://d00886220491a44d49a3ff9d.azurewebsites.net/document/

(Het is een voorlopige URL.)

#6

De voorlopige URL leidt naar:

image
image768×564 35 KB

#7

Je hebt gelijk, dank. Even nagevraagd: de URL is nu alleen intern beschikbaar. Maar dat gaat nog veranderen :wink:

#8

Hoi Willie,
Heb je de API ook eens getoetst met de NL API-strategi die nu in consultatie is?
zie Consultatie API Strategie en Nederlands profiel OAuth | Geonovum

#9

Nee, nog niet. Maar dat ben ik wel van plan. Ik heb al gezien dat de API-strategie hele bruikbare aanwijzingen geeft voor de doorontwikkeling van de subsidieregister API of het opzetten van nieuwe API’s. Dankjewel!