OpenAPI for Web Developers

OpenAPI for Web Developers Lorna Mitchell @lornajane@indieweb.social

About OpenAPI Standard for describing APIs, for machines and for humans. @lornajane@indieweb.social

OpenAPI Example openapi: 3.0.1 servers: - url: http://datasette.local - url: https://datasette.io info: description: Execute SQL queries against a Datasette database and return the results as JSON title: Datasette API version: v1 paths: /content.json: get: description: Accepts SQLite SQL query, returns JSON. Does not allow PRAGMA statements. Credit: https://github.com/APIs-guru/openapi-directory @lornajane@indieweb.social

Code-First vs Design-First @lornajane@indieweb.social

If you wrote the API code already Get an OpenAPI file of what you have, and then start using it design-first. Two great options: •generate from your codebase •use a learning/sniffing tool like Optic @lornajane@indieweb.social

If you wrote the API code already @lornajane@indieweb.social

If you have humans using your API Make the OpenAPI human-readable with docs! •Scalar (next-generation docs) •Redoc (traditional docs) •Bump.sh (short-lived hosted docs) @lornajane@indieweb.social

If you have humans using your API @lornajane@indieweb.social

If your OpenAPI needs editing Designed OpenAPIs can be edited safely But generated ones do have options. •OpenAPI Overlay Specification is a standard for describing edits •Speakeasy and Bump.sh have good Overlay tools •Look out for other transformation tools @lornajane@indieweb.social

Repeatably edit an OpenAPI Part 1 is to prepare the Overlay: •Copy the the OpenAPI file, and edit the copy •Use speakeasy compare creates a diff as an Overlay •Web GUI: https://overlay.speakeasy.com Part 2 is to apply it in every build, locally and in CI •Try the bump or speakeasy CLI tools. @lornajane@indieweb.social

Repeatably edit an OpenAPI @lornajane@indieweb.social

If you have code using your API @lornajane@indieweb.social

If you like API quality and consistency API standards are a document. Use linting to check: •plurals and casing •every operation has an ID •everything named *-date uses the expected format •errors are defined and in the expected format Try: Spectral or Vacuum. @lornajane@indieweb.social

If an API sandbox would be useful Use an API Mock Server tool. Tools include: Microcks, Prism @lornajane@indieweb.social

If an API sandbox would be useful @lornajane@indieweb.social

To avoid API drift Contract testing is your friend! Check that what the API does matches what is described. Tools include: Microcks, WireMock, Pact @lornajane@indieweb.social

To avoid API drift @lornajane@indieweb.social

API Description Pipelines OpenAPI isn’t a static asset. @lornajane@indieweb.social

OpenAPI Community @lornajane@indieweb.social

OpenAPI Community •Part of the Linux Foundation •Standard is developed in the open •https://openapis.org •Public GitHub repository •Active Slack groups •Weekly technical meetings @lornajane@indieweb.social

OpenAPI Standards •Overlays map repeatable amendments to an OpenAPI file (v1.0.0) •Arazzo describe a sequence of API calls (v1.0.1) •OpenAPI describes your API for all the tools to use •stable: 3.1.1 •planned: 3.2.0 •early days: 4.0 “Moonwalk” @lornajane@indieweb.social

OpenAPI Open standard for API descriptions @lornajane@indieweb.social

Resources •https://lornajane.net •https://openapis.org •https://github.com/opticdev/optic •https://speakeasy.com •https://bump.sh •https://microcks.io/ •https://apisyouwonthate.com/ @lornajane@indieweb.social