Documenting SQS event-driven APIs with AsyncAPI
After two or three times, people who didn’t work with our codebase started remembering where the information was and stopped asking altogether. At least when it came to synchronous HTTP APIs. But as the previous question disappeared, another, slightly different one arose:
And the answer was not as easy. Finding it involved diving into the code, looking at DTO and data mapping objects, or even ancient Slack messages. While the HTTP API documentation was stored in a well-known file, everything event-driven API related was scrambled around. Wouldn’t it be nice if we could deal with both the synchronous and the asynchronous APIs in the same way? Turns out, we can!
Asking around, I stumbled upon AsyncAPI, a specification just like OpenAPI, but made for Event-Driven Architectures. Just like with OpenAPI, it describes how to communicate with an application, defining channels and message formats. Let’s see how to use it with an example.
One of the requirements was a way to notify an event to our provider, only once. We decided to use SQS, an AWS message queueing service, into which our backend publishes messages with a specific format, and the provider listens to them.
