PHP UK Conference 2025: Lorna Mitchell talks all things OpenAPI
One of my highlights from this year's PHP conference was Lorna Mitchell's talk, advocating for the use of OpenAPI. At first it seemed like it might have been quite a dry subject: someone else telling me to write better documentation? Great, just what I’m going to want to do next time I’ve got a project deadline looming. However, as the talk went on, I started to see what was in it for tech developers, and why OpenAPI is more than just another set of nice-to-have conventions.
Some background: what's an API, and why should it be open?
APIs are the means by which one web service interacts with another web service. Let's take a specific web service as an example, Sendgrid.
If you want to send an email from your site, you can try sending it directly to the recipient's email service. You can send it to GMail, and they'll probably pass it on. However, if there's any funny business from you, you are liable to get blacklisted, and your emails will go silently into everyone's Spam folder.
Instead, you can send your emails to a company like Sendgrid, who act as a trusted intermediary between you and the email providers - not just GMail, but Outlook, Apple Mail and so forth. In return for behaving yourself and not spamming people, Sendgrid will do their best to make sure your emails are trusted at the recipient's end.
How do you pass your emails to Sendgrid? You use an API. This is the technical under-the-hood means by which your website communicates with Sendgrid. It's in Sendgrid's business interests to make this process as painless as possible, and they help by publishing detailed documentation in an agreed format - in their case, OpenAPI.
Sendgrid's OpenAPI specification is published in a public location so that any developer can see how to use it. Here's an example, written in YAML ("Yet Another Markup Language"), though there is a similar standard for JSON.
Even if you’re not techically minded, you can see that it includes descriptions of what the API does, and that the word “example” crops up a lot. This is part of a comprehensive description of the whole API, in sufficient detail that we can effectively mimic it.
The OpenAPI Method
Lorna began by giving an overview of how you do things the OpenAPI way. If you want it straight from the source, you should visit the OpenAPI website - https://www.openapis.org/ - but here's what I took home. If you want to build your own API, you would:
Write the specification as YAML, like in the link above
Get input on the YAML itself from all interested parties, revise and finalise it accordingly
Only then do you start development work and actually build the API
If the API and the specification differ, the API needs to change, not the specification
What are the advantages of this? Well, there are lots, but here are some edited highlights:
You guarantee there's some documentation! I've often been in the position where trying to get instructions for someone else's API has been like getting blood from a stone
You can check that your specification matches the OpenAPI standards. There are tools you can use for this like Spectral
You can use your YAML and a tool like Prism to set up a mock version of your API, which can mimic any examples you describe in the specification
You can then compare the mock server and your actual API to make sure that your built API is working like it ought to.
What's more, you can take someone else's OpenAPI specification and set up a mock server based on it. For example, you could set up a mock Sendgrid and check that your website can communicate with it. Your mock server won't send any emails out, but it's an excellent way of testing that your integration will work when you point your website at the real API.
In an ideal world, every API would have a sandbox environment - a version of the API which everyone can poke and test without any danger of adverse consequences. However, sandboxes take time and money to run and maintain, and often don't quite replicate what happens in the real world. OpenAPI seems like a great way to address some of these concerns - access to test environments, and consistency of function between development and production.
What will I do differently in future?
Integrating with other people's APIs is not something I do every day. However, my past experiences have not always been great, and I am all for any initiatives that reduce the pain involved. If I have a choice of providers for a service to integrate, the presence or absence of OpenAPI will definitely help sway me towards one or the other. And if I’m involved in the creation of a new API, whether I’m building it or I’m going to be using it, I’ll put in a vote for using OpenAPI from the get-go.
Lorna Mitchell covered a lot of other ground in her talk, and I would be doing her a disservice to misremember more of it. Read more on her blog.