Stöd för OpenAPI på Sveriges dataportal

[Kristine_]

En bra dokumentation om API:er är en förutsättning för att data ska kunna utforskas och användas för digital innovation. Vill tipsa om att Sveriges dataportal gör nu ett test för att stödja en enklare utforskninga av API:er som är beskrivna med OpenAPI-specifikationer, och samtidigt uppmuntra att fler organisationer ska dokumentera sina API:er på ett sådant sätt som stödjer OpenAPI.

För mer information, läs här på dataportalens nyhet: https://bit.ly/3FQBiKX

[jonass]

@kristine_ Till synes en enkel funktion. Men en långsiktig effekt borde bli att alla organisationer inte behöver sätta upp en egen infrastruktur (dokumentationssajt) för att tillhandahålla API:er bland annat. Små saker som kan göra stor skillnad känns som framtidens melodi.

Ett förbättringsförslag är stöd för "deep linking", länk till Sveriges kommuner:
https://taxonomy.api.jobtechdev.se/v1/taxonomy/swagger-ui/index.html#/Specific Types/get_v1_taxonomy_specific_concepts_municipality

På dataportalen https://www.dataportal.se/sv/datasets/180_3963/taxonomi-api/apiexplore/3962#/ går det inte länka till specifika endpoints idag.

[jonor]

Finns det några tankar eller rekommendationer kring HATEOAS i relation till OpenAPI/Swagger angående självbeskrivande API:er?

[jonass]

@jonor HATEOAS finns omnämnt i den svenska nationella API-profilen som DIGG arbetar med i byggblocket API-hantering, publiceras snart. Svårt att rekommendera det som ett skall-krav för API:er dock, att gå från inget API till HATEOAS på första försöket för en organisation är en utmaning. Även om jag personligen gillar idén har jag svårt att hitta bra exempel på dynamiska klienter som faktiskt nyttjar styrkan med HATEOAS. Ge gärna bra exempel om du har.

[jonor]

@jonass Jag har inte någon praktisk erfarenhet, men såvitt jag förstått verkar HATEOAS påminna mer om hur webben redan fungerar. I det avseendet borde det ju kännas mer intuitivt eller bekant för en användare, och utvecklingsmässigt mer likna designen för en webbplats eller webbapplikation där klienten är en webbläsare. Att gå från inget API direkt till HATEOAS kanske i så fall kan vara enklare än att bygga om ett befintligt API med statisk specifikation?

Projektet med SL:s nya API verkar visserligen ha drabbats av förseningar, om nu detta kan ha ha att göra med valet av API-design är svårt att veta såvida de inte rapporterar öppet om utvecklingsarbetet.

https://www.trafiklab.se/news/2020/2020-06-26-new-sl-apis/

The API is RESTful and supports HATEOAS implying simpler error handling and navigation of information.

The new SL API ”Public transport information Region Stockholm” replacing today’s 7 SL APIs at Trafiklab

The new SL API has been delayed to Q1 2021. We will update you when we know more.

SL launched its first open APIs in 2014 and today there are 7 APIs with a functionality that has gradually been extended. These services have been used extensively, and SL has received valuable feedback that has been used as part of the basis for the design of the new open SL API.