Hvad er Open API?

Af Christian H. Fogelberg d. 01.05.2018
Softwareudvikler hos Knowledge Cube

Integrationer og data bliver til stadighed mere vigtigt – og med det er integrationssnitflader og -sikkerhed pludselig blevet et forretningskritisk element i enhver IT-løsning. Så hvorfor ikke gøre det nemt at gå til for både udviklere og forretning?

Et dyk i den uendelig jungle af buzzwords indenfor IT afslører at Swagger-teknologien er blevet voksen under navnet OpenAPI. Så nu skal der selvfølgelig kradses lidt i den nye, voksne overflade for at afdække om der gemmer sig noget af værdi nedenunder.

OpenAPI har eksisteret under navnet siden 2016, og kan på den måde næppe kaldes nyt længere. Med en version 3 (3.0.0.0) fra 2017 er det dog blevet så stabilt, at både typiske og de lidt mere specielle brugsscenarier kan håndteres fornuftigt. Og netop det gør det til et interessant værktøj for udviklere, der skaber skræddersyet IT. I Knowledge Cube er OpenAPI derfor langsomt men sikkert ved at finde ind i alle vores løsninger. Her skal det være med til at højne tilgængeligheden af API’er og data for både interne ressourcer og kundernes øvrige IT-leverandører.

Men hvad er OpenAPI? Beskrivelsen vil vi helst overlade til teamet bag selv, som kort og præcist beskriver det på Swagger-sitet:

What Is OpenAPI?

  • OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including:
  • Available endpoints (/users) and operations on each endpoint (GET /users, POST /users
  • Operation parameters Input and output for each operation< Authentication methods Contact information, license, terms of use and other information.
  • API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines.
  • The complete OpenAPI Specification can be found on GitHub 

Kilde

Det interessante ved OpenAPI er desuden, at der er så mange tools, der understøtter formatet, på tværs af programmeringssprog. Blandt dem, er vi indtil videre meget begejstrede for et par, der skal fremhæves her:

  • Med Swagger Editor kan man starte med at skrive sin OpenAPI specification, for så at bruge Swagger Codegen til at generere server stubs og klienter.
  • I vores forretning er de særligt glade for Swagger UI, hvor de kan læse OpenAPI specifications og gennem et UI klikke rundt samt kalde og teste operationer på API’et direkte fra en browser.
  • Swashbuckle nuget-pakken kan autogenerere OpenAPI specification-dokumenter ud fra implementerede ApiControllers i .Net kode og endda trække kodekommentarer med over i specifikationen. Det betyder, at man som udvikler får en slags selvdokumenterende API, hvis man (bare) har kommenteret sine endpoints, operationer og input/output-modeller ordentligt i koden.

Derudover findes der et stort antal eksterne sites, som tilbyder overvågning af OpenApi specification dokumenter, så man kan få at vide, hvornår der er ændringer. En ønskedrøm for kunder, der har prøvet, at alting brager ned, fordi ”nogen” ændrer noget, men glemmer at informere deres dataaftagere om det – eller bare glemmer at opdatere dokumentationen til de udviklere, der skal integrere til API’et efterfølgende.

Kort sagt, så giver OpenAPI os et virkeligt godt udgangspunkt i vores arbejde. En typestærk klient med kommentarer, som nærmest er selvdokumenterende, mulighed for overvågning af specifications samt adgang til gennemsyn og test af API’erne for forretningen via et UI. Mums!