Member-only story
AWS WebSockets: Writing Documentation Using Async API Spec
A critical but often overlooked piece to a great API is documentation. Explore how to properly document an event-driven architecture with Async API Spec
Remember the last time you integrated with a third-party API? How did you do it? Was it easy?
Step one for any integration is to look at the docs. If there is no documentation, there’s approximately 0% chance you will integrate with that service successfully.
A portion of software that developers often hate as much as writing unit tests is building API specification docs. Unfortunately for them, it is required if you want any kind of success with your integrators.
I’ve written blog posts on the documentation process for REST APIs before using Open API Spec. It’s a remarkable tool that allows you to extend it easily to meet your needs.
But we’re in a different world with WebSockets. This isn’t your grandma’s old school API. This is event-driven architecture in AWS. This is an entirely different ballgame.
We’re going to focus on how to document the API using Async API Spec. This spec allows us to define channels instead of endpoints that describe how consumers can interact with the system.
If you haven’t been following along, this is part three of an Intro to AWS WebSockets series. I highly encourage you to read the first two parts as each post is building on the one before it.
Async API Specification
The API we have built so far in AWS has two event-based interactions:
- A WebSocket that users can subscribe to for entity updates
- An EventBridge event that triggers a push notification in the WebSocket
With a traditional Open API Spec, we don’t have any options to inform consumers about schemas, connection information, or possible interactions with events. It is not what that spec was designed to describe. That spec describes synchronous REST API endpoints.
