Stabiele opvolger Open API Specification 2.0 (voorheen Swagger) eindelijk klaar

Groot nieuws in API wereld: de langverwachte opvolger van OASv2 (voor velen beter bekend als Swagger) is eindelijk daar! Gisteren maakte het Open API Initiative bekend dat de 3.0 versie van de Open API Specification (OAS) eindelijk final is. Door de collaboratie tussen verschillende grote partijen zoals Google, Microsoft, IBM en Adobe, de Open Source Community én individuele API developers, API gebruikers en API architecten, belooft deze versie van de populaire API modelleertaal een enorme stap voorwaarts voor de API economie te worden.

Na de adoptie van de Linux Foundation eind 2015 kwam de doorontwikkeling van Swagger in een stroomversnelling. Naast Swagger waren met name RAML en Apiary populaire middelen om API specificaties op te stellen, elk met hun eigen voor- en nadelen. Een groot nadeel van deze 'concurrentiestrijd' was dat er verschillende communities naast elkaar leefden. Met de totstandkoming van één nieuwe standaard, waar ook de bedrijven achter RAML en Apiary zélf aan hebben bijgedragen, komen deze communities samen en kunnen ze hun krachten bundelen. Bepaalde nadelen van Swagger ten spijt zijn het vooral de community voordelen waardoor wij met ons bedrijf Apiwise voor de meeste projecten het gebruik van Swagger adviseren.

Eén van de nadelen van Swagger (of OASv2, het is maar net hoe je het noemt) waar wij het meest last van hebben is de ontbrekende ondersteuning voor verschillende mediatypes. Als een API response bijvoorbeeld zowel platte JSON (application/json) als Linked Data in de vorm van JSON-LD (application/ld+json) terug moet geven, dan is dat met Swagger niet te modelleren. Een ander praktisch voorbeeld waar we bij overheidsprojecten mee te maken hebben is het verschil tussen mediatypes per statuscode. Als je foutmeldingen zoals een 404 not found terug wilt geven via de RFC-7807 standaard (application/problem+json) dan is dat onmogelijk te modelleren met de 'oude' spec. Uiteraard hebben ook wij een (klein) steentje bijgedragen aan de nieuwe Open API Specification en zijn daarom uiterst verheugd dat dit uiteindelijk een van de features is die het tot de nieuwe release van Swagger's opvolger geschopt heeft.

OASv3 komt daarnaast met veel meer killer features, zoals uitgebreide ondersteuning voor semantic versioning, ondersteuning voor callbacks, uitgebreidere voorbeeldresponses en, last but not least, het beschrijven van webhooks. Alle features van de Open API Specification 3.0 vind je in de Github repository van het project.

Hoewel de release van OASv3 geweldig nieuws is, zullen we het in productie omgevingen voorlopig echter nog wel even met good old Swagger, RAML, Apiary, of iets anders moeten doen. OASv3 is namelijk niet backwards-compatible. Dit betekent dat tools, libraries, frameworks, visualisaties en legio andere toepassingen die ooit voor Swagger gemaakt zijn, niet compatible zijn met de nieuwste versie en drastisch aangepast moeten worden om ook met OASv3 te kunnen werken.

Al met al ben ik er van overtuigd dat de release van OASv3 op termijn het leven van de API Evangelist nog veel rooskleuriger maakt en er betere API's ontwikkeld kunnen worden waardoor systemen, apps, 'things' en andere clients nóg makkelijker en beter met elkaar overweg kunnen ten behoeve van betere dienstverlening aan de eindgebruiker, kostenbesparingen, nieuwe business opportunities en het beantwoorden van maatschappelijke vraagstukken. Het duurt even, maar dan heb je ook wat. ;-)