OpenAPI

At dokumentere en forståelig HTTP-API-kontrakt

OpenAPI er en standard til beskrivelse af HTTP-API’er. En OpenAPI-beskrivelse fastlægger blandt andet de tilbudte stier, operationer, parametre og svarstrukturer. Den kan repræsenteres som JSON eller YAML. Beskrivelsessproget er uafhængigt af det programmeringssprog, tjenesten er bygget i.

Et fiktivt softwarefirma planlægger GET /projects/{projectId} til sin projektportal. Beskrivelsen skal definere projectId som stiparameter; det vellykkede svar 200 skal blandt andet indeholde tekstfeltet name. Kendte fejlsvar hører også til kontrakten. Stien og felterne er vores egne designeksempler, ikke et fuldstændigt OpenAPI-dokument eller en eksisterende tjeneste.

Frontendteamet kan herudfra forstå, hvilke oplysninger det skal sende, og hvilke svar det skal håndtere. Filen alene viser dog ikke, om den kørende implementering følger kontrakten. Før overdragelse skal beskrivelsen sammenholdes med de faktiske svar, også ved fejl. Betydningen af name skal ligeledes aftales: En tekst med korrekt type forklarer ikke, hvilket navn feltet indeholder.

Kilder

• OpenAPI Initiative · OpenAPI Specification