{"id":221,"date":"2021-02-02T20:01:24","date_gmt":"2021-02-02T20:01:24","guid":{"rendered":"https:\/\/fde.cat\/?p=221"},"modified":"2021-02-02T20:01:25","modified_gmt":"2021-02-02T20:01:25","slug":"asyncapi-and-openapi-an-api-modeling-approach","status":"publish","type":"post","link":"https:\/\/fde.cat\/index.php\/2021\/02\/02\/asyncapi-and-openapi-an-api-modeling-approach\/","title":{"rendered":"AsyncAPI and OpenAPI: an API Modeling Approach"},"content":{"rendered":"

AsyncAPI<\/a> is gaining traction in the ecosystem of API tools. It solves an important problem: it provides a convenient way of describing the interface of event-driven systems independently of the underlying technology. With AsyncAPI, evented systems can be treated as any other API product: a productizable and reusable, self-describing building block encapsulating some set of data and capabilities. AsyncAPI also provides an essential component required to develop tooling taking advantage of a way of describing a standard interface for the asynchronous API in order to support the full development cycle of the evented\u00a0system.<\/p>\n

The downside of the rise of AsyncAPI is that it introduces yet another specification and industry standard in an already fragmented API landscape: OAS<\/a>, GraphQL<\/a>, gRPC<\/a>, OData<\/a>, RAML<\/a> and now AsyncAPI<\/a> all provide solutions to understand through metadata the interface of modern APIs and they do it with different degrees of overlap. This can sometimes lead to confusion about the relationship between all these technologies and when to use each of\u00a0them.<\/p>\n

\"\"<\/figure>\n

At MuleSoft, we have long embraced a multi-spec, metadata-driven approach to API interfaces. We developed our open-source parsing and metadata framework, AMF<\/a>, to support the API development lifecycle of our customers and their API supply chain, no matter what specific technologies they want to\u00a0use.<\/p>\n

Our approach is based on defining a formal model that captures the semantics of the different specification languages. We achieve that by mapping elements of the specification syntax to a well-defined taxonomy of concepts in a modeling vocabulary<\/a>. Then, when we parse API definitions in the specification languages, we generate a graph of metadata where each node and edge is mapped to one of the concepts in the modeling vocabulary. We capture in a standard way the data model and semantics of the information provided by the API definition document.<\/p>\n

If two specs overlap in their meaning, we map them to the same common concepts. This allows us to identify the overlap between the different specification languages.<\/p>\n

In our framework, we use well-tested W3C standards (e.g. JSON-LD<\/a>, SHACL<\/a>) that give us a solid foundation to build sophisticated tooling on top of the graph of metadata. The use of standards also gives us access to an array of battle-proven industry tools to work with the API\u2019s metadata, like Amazon Neptune<\/a> for metadata\u00a0storage.<\/p>\n

So when we need to support a new type of spec, the first question we ask ourselves is, what are the semantics of this API specification language? In other words, what type of APIs is it trying to describe? Answering this question is not always easy. Industry-driven specification languages usually lack well-defined semantics and can be ambiguous. They usually provide some grammar and schema information about the syntax of the specification but just some informal textual description of the meaning of those elements. The task of understanding and formally capturing the underlying meaning of the spec is sometimes a confusing one.<\/p>\n

OpenAPI (OAS, before Swagger) is an interesting example. It has been described as a \u2018web API language\u2019 and many people think of OAS as a standard way of specifying \u2018RESTful\u2019 APIs.<\/p>\n

When we added support for OAS, we modeled it as a \u2018web RPC\u2019 language. What we mean by this is that OAS is not describing canonical REST APIs (resources, hypermedia, HATEOAS), although you can define conventions to store a REST model in OAS. Rather, it is describing a classic RPC mechanism that uses HTTP as the transport layer.<\/p>\n

At the core of our RPC model for OAS, there is a list of endpoints bound to HTTP URLs exposing operations bound to HTTP methods, expecting and returning HTTP encoded parameters and payloads.<\/p>\n

\"\"<\/figure>\n

Additionally, JSON Schema is the usual way of describing the data structures being exchanged in the messages. We modeled these schemas using SHACL, the standard W3C language for data shapes, with some extensions<\/p>\n

\"\"<\/figure>\n

This web RPC model has allowed us to model other \u2018RESTful\u2019 specification languages like RAML using the same common underlying vocabulary.<\/p>\n

When we started looking at AsyncAPI, the same question came to mind: what are the actual semantics of AsyncAPI? What type of systems is AsyncAPI trying to describe?<\/p>\n

AsyncAPI introduces a key concept in the way it makes it possible to define evented systems. It defines a conceptual boundary around the system, delimiting and encapsulating the internal implementation and the external set of clients consuming and producing information.<\/p>\n

These clients interact through a well-defined interface accessible through multiple channels, exposing two asynchronous operations: publish and subscribe. The semantics of these operations are not clearly defined but they can be understood as asynchronous, non-blocking write and read operations.<\/p>\n

\"\"<\/figure>\n

This boundary makes it possible to look at the evented system as similar to traditional client-server architectures of synchronous RESTful APIs as defined by\u00a0OAS.<\/p>\n

This simple model is also incredibly useful in order to treat the evented system as an atomic component that can be reused and provides a clear contract with the exterior, unlocking a lot of productization and lifecycle use cases around the evented\u00a0system.<\/p>\n

The second interesting aspect of AsyncAPI when compared to traditional synchronous HTTP based RPC APIs is that AsyncAPI needs to support multiple transports. There are many technologies that can satisfy the simple interface introduced by AsyncAPI. Many of these transports introduce complex application level protocols, but, in the same way OAS uses HTTP as a transport without reusing the application level semantics of the protocol, AsyncAPI can abstract these details and still provide value through the abstract asynchronous operations described in the specification.<\/p>\n

However, in order to actually invoke the operations from the external consumer point of view, the abstract operations must be bound to some actual transport component. AsyncAPI bindings capture how to bind that abstract element to the concrete protocol information required to publish and subscribe to the\u00a0events.<\/p>\n

\"\"<\/figure>\n

From this point of view, we model AsyncAPI as an asynchronous RPC API mechanism with multi-transport bindings. This allows us to encode AsyncAPI specifications in the same graph of metadata with the common semantics we are generating for RAML\/OAS, with some minor adjustments:<\/p>\n