OpenAPI
OpenAPI beskriver HTTP-grensesnitt maskinlesbart med stier, parametere og svar. Beskrivelsen må samsvare med tjenesten som kjører.
Å dokumentere en forståelig HTTP-API-kontrakt
OpenAPI er en standard for å beskrive HTTP-API-er. En OpenAPI-beskrivelse angir blant annet stier, operasjoner, parametere og svarstrukturer som tilbys. Den kan representeres som JSON eller YAML. Beskrivelsesspråket er uavhengig av programmeringsspråket tjenesten er bygd i.
Et fiktivt programvareselskap planlegger GET /projects/{projectId} til prosjektportalen sin. Beskrivelsen skal definere projectId som stiparameter; det vellykkede svaret 200 skal blant annet inneholde tekstfeltet name. Kjente feilsvar hører også til kontrakten. Stien og feltene er våre egne designeksempler, ikke et fullstendig OpenAPI-dokument eller en eksisterende tjeneste.
Frontendteamet kan dermed forstå hvilke opplysninger det skal sende og hvilke svar det skal håndtere. Filen alene viser likevel ikke om implementeringen som kjører følger kontrakten. Før overlevering må beskrivelsen sammenholdes med de faktiske svarene, også ved feil. Betydningen av name må også avtales: En tekst med riktig type forklarer ikke hvilket navn feltet inneholder.
Kilder
Beslektede begreper
- APIEt API fastsetter hvordan programvare kan bruke funksjoner eller data fra annen programvare.
- RESTREST beskriver arkitekturregler for distribuerte grensesnitt. Ressurser, tilstandsløse forespørsler og lenker inngår i tilnærmingen.
- Server-Sent EventsServer-Sent Events sender tekstmeldinger fra server til klient via HTTP, for eksempel om fremdriften til en bakgrunnsjobb.
- ETagEn ETag identifiserer en bestemt representasjonsversjon av en HTTP-ressurs og støtter betingede oppslag eller endringer.
- Cross-Origin Resource SharingCORS styrer nettleserens tilgang til svar fra en annen origin. Det erstatter verken API-innlogging eller kontroll av rettigheter.
- Elektronisk datautvekslingEDI overfører strukturerte forretningsdokumenter mellom systemer. Format, partnerprofil, datakoblinger og tilbakemeldinger må stemme overens.
Ditt prosjekt med ASES
Beskriv prosjektet ditt for oss. Vi tar kontakt med en første vurdering.