Documenting Outbound APIs
How do you document the APIs your partners and customers need to build so you can interact with them?
Having to build an API just to be able to interact with a product isn’t pleasant. One thing is to put together an integration with an API. Something entirely different is building and maintaining your own API so the product you’re using can integrate with it. Take, for example, receiving a request from Stripe whenever someone makes a payment. Or, building an API so you can make your product available on Zapier as an integration. Or even preparing to receive notifications from HubSpot whenever a new sale is closed. These are all called outbound APIs and exist to let products share information externally with partners and customers. How do you document these APIs so they’re easier to understand and build? Keep reading to explore different approaches.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
I recently participated in a project related to the exchange of information with business partners. One of the goals was to allow external entities to share information with my organization. The second goal was to allow the same thing but in an inverse direction. We wanted to be able to share information with partners in a consistent and predictable fashion. We didn’t want to have to reinvent the format of the data we wanted to share every time we interacted with a new partner. We didn’t want to renegotiate with new partners on how often we would share information. We wanted a simple solution that could provide a programmatic way of sharing information and dealing with potential errors. What we needed was definitely an API. But not just any API. We needed an outbound API.
Our idea was to define the outbound API once and then ask each partner to implement it on their side. The first question we had was how to define and document the outbound API so partners could understand how they would implement it. I suggested starting by understanding the needs of the future API consumers, but I quickly realized that I was making a mistake. The API consumers were ourselves, not our partners. And we already knew what our needs were. What we had to understand was the technical capabilities of our partners so we could decide how to define our outbound API. But how would we share the documentation with our partners, and what else could we provide to help them build the API?
One option to define an outbound API is to see it as a callback or even as a webhook. The OpenAPI specification supports callbacks on version 3.0 and webhooks on version 3.1. It sounds like a good choice if the outbound API is associated with an inbound API. You should consider something else if, on the other hand, the outbound API is somehow disconnected from everything else. Or, if you don’t have any inbound APIs. In that case, your best bet is to create a standalone OpenAPI document just for the outbound API. This is, in fact, the solution that looks the easiest and is the one we ended up exploring first.
Sharing a standalone outbound API definition is as simple as creating its OpenAPI document and making it available to your partners. They will then use the definition to implement the API and share its base URL with you. This would be the very minimal user experience, I’d say. However, it can be much better than this. There are two interactions that can be automated. One is the sharing of the OpenAPI document, which you can do using a private API catalog that you invite your partners into. After they sign in, they can access the API definition, download the OpenAPI document, and share the base URL of their API. At that point, your system can start making requests to your partner’s API. However, this approach didn’t cover all our partners’ needs.
We soon realized that, in addition to receiving information from us, our partners also wanted to subscribe to events related to some of our API operations. They wanted to be notified whenever a long-running operation ended. We turned to OpenAPI’s callbacks to define the behavior of those notifications. OpenAPI 3.0 lets you define a callback as an operation whose path can either be static or can even be obtained from an input parameter, or even from a response element. This gives great flexibility to the way you can define and handle callbacks. To achieve even more flexibility, you can use the webhooks feature of all versions of OpenAPI greater than 3.1. While a callback is tied to a particular operation, a webhook isn’t, making it the ideal way to define server-initiated outbound operations that aren’t necessarily reacting to an inbound operation.
As you can see, there are plenty of ways to define outbound APIs. Still, pay attention to the level of support different tools offer. The first option I presented is almost guaranteed to work with any tool because it’s a simple OpenAPI document. The other two solutions, however, might not work in all situations. It’s important to identify what programming language and framework your partners use to understand what level of support they can get. Of course, it’s always possible to implement things by hand. In other words, you don’t need any tool to implement an outbound API. Yes, this is true, but it can be painful to maintain whenever the definition of the outbound API changes.
Overall, defining and implementing an outbound API shouldn’t be too complicated. If you work with partners and external entities, you’ll end up needing an outbound API sooner or later. Whether you choose to use a full OpenAPI document, work with callbacks, or define webhooks depends on how sophisticated your partners are and the level of support they need.