The OpenAPI Standards Landscape: A Year of Innovation

The OpenAPI Standards Landscape: A Year of Innovation Lorna Mitchell @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI Standards OpenAPI Intiative publishes three open standards for APIs: •OpenAPI: describe an API •Overlay: describe improvements to an API •Arazzo: describe a sequence of API calls @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI How to describe an API: •overview •endpoints •requests •responses •security YAML or JSON format @lornajane@indieweb.social, @lornajane.net (bsky)

Overlay @lornajane@indieweb.social, @lornajane.net (bsky)

Overlays Improve OpenAPI Overlays describe a series of “actions” to update or remove parts of an OpenAPI description. Common use cases: •remove private/internal endpoints before publishing •improve summary/description/example values •add tool-specific extensions •fill in repeated content like error responses @lornajane@indieweb.social, @lornajane.net (bsky)

Overlay Example Add a tag to all DELETE operations overlay: 1.0.0 info: title: Tag delete operations as restricted version: 1.0.0 actions: - target: $.paths.*.delete update: tags: - x-restricted Actions are executed in the order they are declared @lornajane@indieweb.social, @lornajane.net (bsky)

API Description Pipelines OpenAPI description is not a single file. •combine sources into one description •improve and fill gaps if needed •send file to multiple destinations (docs, SDKs, etc) •apply destination-specific transforms on the way @lornajane@indieweb.social, @lornajane.net (bsky)

Arazzo @lornajane@indieweb.social, @lornajane.net (bsky)

Arazzo Arazzo describes sequences of API calls. Outline complex API workflows so that: •documentation can describe the steps •SDKs can wrap multiple API calls into one task •multi-step API scenarios can be tested @lornajane@indieweb.social, @lornajane.net (bsky)

Arazzo Structure Arazzo describes: •workflows •containing steps •can reference OpenAPI descriptions •steps have success and failure criteria •input variables and step outputs can be used in later steps @lornajane@indieweb.social, @lornajane.net (bsky)

Arazzo Example arazzo: 1.0.0 info: title: Public Zoo API version: ‘1.0’ sourceDescriptions: - name: animals type: openapi url: ./animals.yaml workflows: - workflowId: animal-workflow parameters: # … steps: - stepId: get-step operationId: $sourceDescriptions.animals.getRandomAnimal @lornajane@indieweb.social, @lornajane.net (bsky)

Arazzo Workflows Use Arazzo: •for your own APIs •to improve integrations and consume APIs •for testing •and more to come @lornajane@indieweb.social, @lornajane.net (bsky)

What’s Next in OpenAPI @lornajane@indieweb.social, @lornajane.net (bsky)

What’s Next in OpenAPI •”soon” : OpenAPI 3.2 •additional security fields •path/URL templating improvements •extended and nested tags •”later”: OpenAPI 4.0 •project codename: Moonwalk @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI Community @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI Community Start here: https://openapis.org •Public GitHub activities •Slack for discussions •Regular public meetings for various groups •Newsletter to get some high-level updates @lornajane@indieweb.social, @lornajane.net (bsky)

OpenAPI Landscape @lornajane@indieweb.social, @lornajane.net (bsky)

Resources •https://openapis.org •https://lornajane.net •https://apisyouwonthate.com/ @lornajane@indieweb.social, @lornajane.net (bsky)