Als je gaat starten met het ontwikkelen van een API zijn er verschillende manieren om dit aan te pakken. In de praktijk zie je grofweg 2 verschillende methoden: "design-first" en "code-first". In dit artikelen leggen we uit wat de verschillen zijn en waarom de "design-first" aanpak wat ons betreft de voorkeur heeft.
Ik denk juist dat een combinatie goed werkt (en niet een polder oplossing is). Samen designen en ontwikkelen. Bij VNG Klantinteracties vond ik dat persoonlijk erg prettig werken.
Als er goede richtlijnen zijn over hoe NL APIs er uit moeten zien, dan heb je het geschetste probleem ook helemaal niet. Een API vanuit code moet zich hier dan gewoon aan houden.
Net zoals de API designer, die ook niet allerlei vrijheden moet nemen wat tot steeds verschillende API-structuren leidt of juist structuren enkel maakt omdat de tool niets anders biedt (hallo JSON-HAL).
De NL API strategie, waar ik groot fan van ben al sinds het nog een DSO aangelegenheid was, laat het op veel van dit soort concrete punten afweten (zie paginering, zie relaties cross API, etc).
We hebben toch genoeg gezien hoe specificaties (APIs of SOAP) er uit zien als deze enkel vanuit de ivoren toren worden bedacht. Dit moet echt samen zodat meteen beproeft kan worden.
Maar goed, Kadaster/Geonovum zijn vaak designer, bouwer en (de enige) aanbieder van een API wat een andere situatie is dan standaarden maken. Wellicht werkt in verschillende scenario’s verschillende aanpakken het beste.
Helemaal mee eens, ontwikkelaars moeten en kunnen prima (mede) verantwoordelijk zijn voor het API design. Een samenwerking tussen meerdere disciplines lijkt me zelfs het meest ideaal. Het punt wat in het artikel wordt gemaakt heeft meer betrekking op het proces (los van wie waarvoor verantwoordelijk is), om te voorkomen dat een API spec iets is wat reverse-engineered wordt vanuit de code.
Wordt dit ‘in de buitenwereld’ niet vooral ‘API First’ genoemd, Joost?
“API First” betekent dat je eerst een API maakt en daar zelf gebruik van maakt in je applicatie (bijvoorbeeld frontend) ipv dat je eerst een hele applicatie maakt en daarna los een API aanbiedt voor derden (die je zelf niet gebruikt).