As we work to map out the API landscape as part of our work on the Streamdata.io API Gallery, we are producing an OpenAPI driven map of all the valuable API resources we are profiling. Along the way we are also thinking about how we can simultaneously create a map of the event-driven opportunities that exist across the space, and we are using the AsyncAPI specification to help us accomplish this.
AsyncAPI is a machine readable definition for defining message-driven APIs, that is complimentary to the OpenAPI specification. We are looking to better understand how we can adopt the specification to map out the event, message, and topic driven opportunities that already exists across the API space. One of the areas the AsyncAPI team is pushing forward as part of the specification, is around the concept of a topic—“to create a definition that suites most use cases and establish the foundation for community tooling and better interoperability between products when using AsyncAPI.” or to elaborate further, “a topic is a string representing where an AsyncAPI can publish or subscribe. For the sake of comparison they are like URLs in a REST API.”
Here is an example of topic structure, {organization}.{group}.{version}.{type}.{resources}.{event}, with the following breakdown:
– organization – the name of the organization or company.
– group – the service, team or department in charge of managing the message..
– version – the version of the message for the given service. This version number should remain the same unless changes in the messages are NOT backward compatible.
– type – the type of the message, e.g., is it a command or an event?. This value should always be event unless you’re trying to explicitly execute a command in another service, i.e., when using RPC.
– resources – resources and sub-resources, in a word (or words) describing the resource the message refers to. For instance, if you’re sending a message to notify a user has just signed up, the resource should be user. But, if you want to send a message to notify a user has just changed her full name, you could name it as user.full_name.
event – an event or command name, in case message type is event, this should be a verb in past tense describing what happened to the resource, and in case message type is command, this should be a verb in infinitive form describing what operation you want to perform.
Some example(s) are:
– hitch.accounts.1.event.user.signedup
– hitch.email.1.command.user.welcome.send
As we profile the event-driven architecture of various APIs, we are documenting, and keeping track of the different ways in which API providers articulate their events. Each API provider has their own approach, as there is no existing standard for defining event types, but we want to keep an eye on all existing patterns, aggregate them, and consider the different approaches already in use as we think about contributing to the AsyncAPI topic conversation. So far this week, we have taken a look at common event types for user authentication and authorization, as well as some of the common payment event types. We’ll keep an eye out for common patterns in across other industries, and add them to the mix.
We are looking to settle in on a common vocabulary for defining event types that applies across many different platforms, and helps us describe the event-driven opportunities that exist across the API sector. It will take a significant amount of work, but eventually we are hoping to have identified the most common types of events that are occurring, as well as the highest quality opportunities for subscribing and publishing events to these channels. Before we can get there, we’ll have to keep mapping out the existing API landscape, and help AsyncAPI evolve their approach to defining topics across many different platforms.
Follow us on social