OpenAPI
OpenAPI beskriver HTTP-gränssnitt maskinläsbart med sökvägar, parametrar och svar. Beskrivningen ska stämma med tjänsten som körs.
Att dokumentera ett begripligt HTTP-API-kontrakt
OpenAPI är en standard för att beskriva HTTP-API:er. En OpenAPI-beskrivning anger bland annat erbjudna sökvägar, operationer, parametrar och svarsstrukturer. Den kan representeras som JSON eller YAML. Beskrivningsspråket är oberoende av programmeringsspråket som tjänsten byggs i.
Ett fiktivt programvaruföretag planerar GET /projects/{projectId} för sin projektportal. Beskrivningen ska definiera projectId som sökvägsparameter; det lyckade svaret 200 ska bland annat innehålla textfältet name. Även kända felsvar hör till kontraktet. Sökvägen och fälten är våra egna designexempel, inget fullständigt OpenAPI-dokument eller någon befintlig tjänst.
Frontendteamet kan då förstå vilka uppgifter det ska skicka och vilka svar det ska hantera. Filen ensam visar dock inte om implementationen som körs följer kontraktet. Före överlämning behöver beskrivningen jämföras med de faktiska svaren, inklusive fel. Betydelsen av name måste också avtalas: En text med rätt typ förklarar inte vilket namn fältet innehåller.
Källor
Relaterade begrepp
- APIEtt API anger hur programvara kan använda funktioner eller data som annan programvara erbjuder.
- RESTREST beskriver arkitekturregler för distribuerade gränssnitt. Resurser, tillståndslösa anrop och länkar ingår i arbetssättet.
- Server-Sent EventsServer-Sent Events skickar textmeddelanden från server till klient via HTTP, exempelvis om ett bakgrundsjobbs förlopp.
- ETagEn ETag identifierar en viss representationsversion av en HTTP-resurs och stöder villkorade hämtningar eller ändringar.
- Cross-Origin Resource SharingCORS styr webbläsarens åtkomst till svar från en annan origin. Det ersätter varken API-inloggning eller behörighetskontroll.
- Elektroniskt datautbyteEDI överför strukturerade affärsdokument mellan system. Format, partnerprofil, datamappning och återkoppling måste stämma överens.
Ditt projekt med ASES
Beskriv ditt projekt för oss. Vi hör av oss med en första bedömning.