A presentation at PHPUK 2025 in in London, UK by Lorna Jane Mitchell
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
APIs are at the heart of modern application development, and OpenAPI is a powerful tool to streamline your API development lifecycle. In this talk, we’ll explore how OpenAPI can enhance your projects and how an OpenAPI description evolves through the build process to power up different aspects of your project. Get hands-on examples of the cool tools to use with OpenAPI to transform the API descriptions, produce documentation or client SDKs, or mock up the API for testing. With practical tips and pointers to further resources, this session is perfect for anyone using APIs who wants to make them just a little bit better. Come along and get ready to take the next step in your API journey.
