#asyncapi

[govindhtech]

Mastering the AsyncAPI Specification: A Comprehensive Guide

The AsyncAPI Specification(A2S)

Credit

A portion of this content is derived from the excellent work of the OpenAPI Initiative team.

AsyncAPI 3.0.0 

Within this document, the terms “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted in accordance with RFC 2119 regulations.

The Apache Licence, Version 2.0 governs the use of the AsyncAPI Specification.

Overview

A project called AsyncAPI Specification aims to provide machine-readable descriptions of message-driven APIs. You can use it for APIs that operate over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc.) because it is protocol-agnostic.

A set of attributes that can be used in an AsyncAPI document to describe an application’s API is defined by the AsyncAPI Specification. The document is usually a single main document that contains the API description; it may refer to other files for more information or shared fields.

The actions that an application takes SHOULD be detailed in the AsyncAPI specification.

It indicates that messages from the userSignedUp channel will be received by the application.

Software topology, architecture, or pattern of any type is not assumed by the AsyncAPI definition. As a result, a server could be any type of computer programme that can send and/or receive data, including message brokers and web servers. But AsyncAPI has a feature called “bindings” that tries to assist with more detailed protocol details.

Deriving a receiver AsyncAPI document from a sender document, or the other way around, is NOT SUGGESTED. It is not guaranteed that an application sending messages will utilise the same channel that another application is using to receive them. Additionally, several fields in the document, such as the operation’s id, description, and summary, may cease to make sense.

By swapping out receive for send,IBM cannot presume that an opposing application exists automatically:

In addition to the problems listed above, there might be other configurations of the infrastructure that are not included here. A system might, for example, utilise one read-only channel for messages, another for sending them, and a middleman process to forward messages between the channels.

Definitions

Server

A message broker that can send and/or receive messages between a sender and a recipient MAY be a server. A server could be a WebSocket API service that allows message-driven server-to-server or browser-to-server communication.

Application

Any type of computer programme, or collection of them, is called an application. A sender, a recipient, or both MUST be involved. An application could be a message broker, microservice, mainframe process, Internet of Things device (sensor), etc. Any number of programming languages may be used to create an application, provided that they support the chosen protocol. To connect and send messages, an application MUST also use a protocol that the server supports.

Sender

An application that sends messages to channels is called a sender. Senders may choose to send to more than one channel, based on the use-case pattern, protocol, and server.

Receiver

An application that receives messages from channels is called a receiver. Recipients may get data from various channels, contingent upon the server, protocol, and use-case design. A message that is received MAY be forwarded again by the recipient unaltered. Recipients MAY respond to the communication by acting as consumers. It is possible for a receiver to function as a  processor, combining several messages into one and sending it.

Message

The method by which data is transferred across a channel between servers and applications is called a message. Both headers and a payload are possible components of a message. It is possible for the headers to be separated between header attributes defined by the application and protocol-defined headers, which can serve as supporting metadata. The application-defined data, which must be serialised into a format (JSON, XML, Avro, binary, etc.), is contained in the payload. A message can handle various interaction patterns, including event, command, request, and response, because it is a generic mechanism.

Channel

A channel is an addressable element that the server provides for message organisation. Applications that are senders send messages to channels, and applications that are receivers receive messages from channels. Multiple channel instances MAY be supported by servers, enabling messages with various content types to be addressed to various channels. Protocol-defined headers MAY allow the channel to be included in the message, depending on how the server is implemented.

Protocol

The method (wireline protocol or API) by which messages are transferred between the application and the channel is called a protocol. Mercure, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, and Pulsar are a few examples of protocols.

Bindings

A method for defining protocol-specific data is called a “binding” (also known as “protocol binding”). As a result, a protocol binding MUST only define data related to the protocol.

Specifications

Format

The files that follow the JSON standards and describe the message-driven API in line with the AsyncAPI Specification are represented as JSON objects. An A2S (AsyncAPI Specification) file can also be represented in YAML, which is a superset of JSON.

When a field is said to have an array value, for instance, the JSON array format is employed:

Although the API uses JSON to describe itself, the API does not require JSON input or output.

The specification uses case sensitivity for all field names.

Two kinds of fields are exposed by the schema. Patterned fields specify a regex pattern for the field name, whereas Fixed fields have a specified name. As long as each occurrence of a patterned field has its own name, they can appear more than once.

YAML version 1.2 is advised coupled with a few further restrictions to maintain the ability to round-trip between YAML and JSON formats:

Only tags that are permitted by the JSON Schema standard may be used.

The YAML Failsafe schema guideline stipulates that keys used in YAML maps MUST be restricted to a scalar string.

File Organisation

An AsyncAPI document MAY consist of a single document or, at the author’s option, be composed of several related portions. The latter scenario makes use of Reference Objects.

It’s crucial to remember that, aside from the Components Object, everything defined in an AsyncAPI document MUST be used by the implemented Application. Every definition contained within the Components Object designates a resource that the implemented Application MAY or MAY NOT use.

Asyncapi.json or asyncapi.yaml is the standard name for the AsyncAPI Specification (A2S) file.

URLs that are absolute

RFC3986, section 4.3 defines all characteristics that are absolute URLs, unless otherwise noted.

Schema

AsyncAPI Object

The API specification’s root document object is this one. It is a single document that includes both the API declaration and resource listing.

Read more on govindhtech.com

[improveyourcodingskills]

Generate stunning API documentation · Bump

[oscin]

#AsyncAPI vs #OpenAPI: What’s The Difference? http://bit.ly/2lsREFJ The world of APIs is often one of competing standards, interests, and solutions. While we tend to talk about the API space as a cohesive community, the reality is that APIs on the internet encompasses something more universal. In the API documentation space, this ultimately comes down to a question of consumption. Who is actually using the documentation? What purpose does that documentation serve? How does it drive the product and increase its value? Today, we’re going to look at documentation solutions for two very broad types of APIs: OpenAPI and AsyncAPI. Both of these solutions generate machine-readable documentation, a concept that we will discuss shortly, but they do so for wildly different types of APIs. Why Document? Documentation is universal for technical projects. So much so that it is often seen as important as the code itself. API documentation is essentially a consumption, utilization, and contextualization bible: it serves the purpose of not only informing the end-user but contextualizing and explaining that information to make it useful for some application. #Fintech #Insurtech #Wealthtech #OpenBanking #PSD2 #payments #Cybersecurity (hier: Schiffstation Männedorf) https://www.instagram.com/p/B2HQhS7itS-/?igshid=5ni4h3z9ba2k

[hackernewsrobot]

AsyncAPI vs. OpenAPI: Answers to Your Burning Questions

https://www.asyncapi.com/blog/openapi-vs-asyncapi-burning-questions Comments

[holyjak]

The AsyncAPI specification is an industry standard for defining asynchronous - i.e. message-driven - APIs, for example over WebSockets, HTTP, Kafka. It is the async twin of OpenAPI (formerly Swagger) and describes the available Operations, Messages, subscribable Channels, etc. Plus tools to generate docs, client libraries and server code

[codehunter]

Why do we need middleware for async flow in Redux?

According to the docs, "Without middleware, Redux store only supports synchronous data flow". I don't understand why this is the case. Why can't the container component call the async API, and then dispatch the actions?

For example, imagine a simple UI: a field and a button. When user pushes the button, the field gets populated with data from a remote server.

import * as React from 'react';import * as Redux from 'redux';import { Provider, connect } from 'react-redux';const ActionTypes = { STARTED_UPDATING: 'STARTED_UPDATING', UPDATED: 'UPDATED'};class AsyncApi { static getFieldValue() { const promise = new Promise((resolve) => { setTimeout(() => { resolve(Math.floor(Math.random() * 100)); }, 1000); }); return promise; }}class App extends React.Component { render() { return ( <div> <input value={this.props.field}/> <button disabled={this.props.isWaiting} onClick={this.props.update}>Fetch</button> {this.props.isWaiting && <div>Waiting...</div>} </div> ); }}App.propTypes = { dispatch: React.PropTypes.func, field: React.PropTypes.any, isWaiting: React.PropTypes.bool};const reducer = (state = { field: 'No data', isWaiting: false }, action) => { switch (action.type) { case ActionTypes.STARTED_UPDATING: return { ...state, isWaiting: true }; case ActionTypes.UPDATED: return { ...state, isWaiting: false, field: action.payload }; default: return state; }};const store = Redux.createStore(reducer);const ConnectedApp = connect( (state) => { return { ...state }; }, (dispatch) => { return { update: () => { dispatch({ type: ActionTypes.STARTED_UPDATING }); AsyncApi.getFieldValue() .then(result => dispatch({ type: ActionTypes.UPDATED, payload: result })); } }; })(App);export default class extends React.Component { render() { return <Provider store={store}><ConnectedApp/></Provider>; }}

When the exported component is rendered, I can click the button and the input is updated correctly.

Note the update function in the connect call. It dispatches an action that tells the App that it is updating, and then performs an async call. After the call finishes, the provided value is dispatched as a payload of another action.

What is wrong with this approach? Why would I want to use Redux Thunk or Redux Promise, as the documentation suggests?

EDIT: I searched the Redux repo for clues, and found that Action Creators were required to be pure functions in the past. For example, here's a user trying to provide a better explanation for async data flow:

The action creator itself is still a pure function, but the thunk function it returns doesn't need to be, and it can do our async calls

Action creators are no longer required to be pure. So, thunk/promise middleware was definitely required in the past, but it seems that this is no longer the case?

https://codehunter.cc/a/javascript/why-do-we-need-middleware-for-async-flow-in-redux

[releaseteam]

via Twitter https://twitter.com/releaseteam

[hellowhatisnewposts]

AsyncAPI vs. OpenAPI: Answers to Your Burning Questions 7 by Lagoni |

[govindhtech]

IBM helps OpenSource AsyncAPI break event-driven designs

You may easily specify and record your Kafka topics (event sources) in accordance with the open source AsyncAPI Specification by using IBM Event Automation’s event endpoint management feature.

What makes this significant? AsyncAPI is already a driving force behind things like standardisation, interoperability, real-time responsiveness, and more. Adding this to your environment through event endpoint management enables you to handle the intricacies of contemporary systems and apps with ease.

Since they make it possible for developers to work together efficiently and find, utilise, and expand upon preexisting solutions, Application Programming Interfaces (APIs) and API management are already immensely valuable. Formalising event-based interfaces can provide the same advantages as events, which are used to facilitate communication between applications:

Standardised event description that makes it easy for developers to comprehend what events are and how to use them

Discovering events: Catalogues allow for the addition of interfaces, making them searchable and marketed.

Dispersed access Interface owners can employ self-service access that can be tracked.

Life cycle supervision: Interface versioning helps prevent teams from being unintentionally destroyed by updates.

It is more crucial than ever for organisations to become event driven because consumers want prompt service and they need to be able to quickly adjust to shifting market conditions. Events must therefore be distributed throughout the entire organisation and fully utilised in order for enterprises to act truly agilely. The importance of event endpoint management becomes clear at this point: event sources can be found and used by any user across your teams, and they can be managed simply and uniformly like APIs to securely reuse them across the company.

The ability to describe events in a standardised manner in accordance with the AysncAPI definition is one of the main advantages of event endpoint management. For any Kafka cluster or system that complies with the Apache Kafka protocol, it is simple to create a valid AsyncAPI document thanks to its user-friendly UI.

IBM implementation is expanding the application of AsycnAPI. With the most recent release of their event endpoint management system, client apps can now use the event gateway to publish to an event source. It is now possible for an application developer to create an event source that is added to the catalogue instead of only consuming events. Furthermore, in order to govern the type of data a client can publish to your subject, IBM have included controls like schema enforcement.

IBM provide those more fine-grained approval restrictions in addition to self-service access to these event sources listed in the catalogue. The function of the event gateway controls access to the event sources. It receives requests from applications to access a topic and securely routes traffic between the application and the Kafka cluster.

Open innovation is quickly becoming a key driver of increased revenue and improved company success. Businesses who adopt open innovation saw a 59% greater rate of revenue growth than those that don’t. The IBM Institute of Business Value AsyncAPI is the industry standard for defining asynchronous APIs, and Event Endpoint Management has accepted and promoted it from its creation.

Following the December release of AsyncAPI version 3, IBM began to enable the creation of v3 AsynchAPI documentation for event endpoint management in a matter of weeks. To further support the most recent version 3 improvements, IBM upgraded the open-source AsyncAPI generator templates as part of their giving back to the community. See how to use the AsyncAPI generator templates with ease in IBM discussion on AsyncAPI v3. IBM’s mission to improve the manageability, usability, and accessibility of asynchronous APIs is still being pursued by IBM, which continues to sponsor and support the AsyncAPI community.

AsyncAPI 3.0.0 Release Notes

The AsyncAPI specification has just released version 3.0.0, which is jam-packed with features! Some increase maintainability, some add features, and yet others clarify things.

IBM have divided the information into easily understood sections in order to make it as clear as possible.

If you would like a summary of:

With all of the changes made in version 3, you’re in the correct spot!

A migration guide covering all the significant changes from version 2 to version 3.

Summary

An overview of all the v3 changes is provided in this post.

Decoupling of the operation, channel, and message

Reusing channels was never an option in v2 since it was inextricably linked to application functions.

With the idea that a channel and message should be independent of the actions carried out, this is now feasible in v3. This implies that channels for any message broker, like Kafka, can now just specify topics and the messages they contain. It includes all pathways and associated messages for all request types in the case of REST APIs. It’s all of the messages passing via the WebSocket server in the case of WebSocket. It describes every room and message in Socket.Io.

The channels are now reusable amongst AsyncAPI documents thanks to this modification.

Messages Instead of message

Messages in channels are no longer solitary, as you have likely observed above; instead, with oneOf, messages are defined as key/value pairs in the Messages Object. This was a feature of the request-reply function that made it easy to refer to messages.

Confusion between publish and subscribe

The keywords for the publish and subscribe operations in version 2 have always been unclear. Does this imply that the channel has published my application? Do you mean to post on my behalf? Within this setting, who are you?

IBM attempt to clarify this in v3. All that matters is how your application behaves. No more misunderstandings about who does what or what. IBM accomplish this by introducing two new Operation Object keywords: send and receive. This means that anything can be sent or received by your application.

Naturally, this definition varies slightly depending on the protocol; in the case of generic message brokers, you generate or consume messages, but from an abstract AsyncAPI standpoint, you continue to send and receive messages.

Request/Answer

Request and reply has been a long-awaited feature, and it’s now available!

The publish and subscribe misunderstanding has always been a pain in the neck for this function, making it difficult to come up with a practical solution. But since that’s out of the way, IBM have a solution.

The following use scenarios have been considered in the design of this feature:

Broker-based messaging that includes “correlationId” and a well defined response topic.

Broker-based messaging using “correlationId” + “replyTopic” with individual inboxes for each process.

Broker-based messaging where each individual response has a temporary reply topic.

WebSocket, where messages are sent via a TCP connection and it lacks subjects.

Read more on govindhtech.com

[mp3monsterme]

Useful Quick Reference Links when Writing API Specs

Whether you’re writing Asynchronous or Open APIs unless you’re doing it pretty much constantly, it is useful to have links to the specific details, to quickly check the less commonly used keywords, or to check whether you’re not accidentally mixing OpenAPI with AsyncAPI or the differences between version 2 or version 3 of the specs. So here are the references I keep handy: API Handyman’s…

[codehunter]

Why do we need middleware for async flow in Redux?

According to the docs, "Without middleware, Redux store only supports synchronous data flow". I don't understand why this is the case. Why can't the container component call the async API, and then dispatch the actions?

For example, imagine a simple UI: a field and a button. When user pushes the button, the field gets populated with data from a remote server.

import * as React from 'react';import * as Redux from 'redux';import { Provider, connect } from 'react-redux';const ActionTypes = { STARTED_UPDATING: 'STARTED_UPDATING', UPDATED: 'UPDATED'};class AsyncApi { static getFieldValue() { const promise = new Promise((resolve) => { setTimeout(() => { resolve(Math.floor(Math.random() * 100)); }, 1000); }); return promise; }}class App extends React.Component { render() { return ( <div> <input value={this.props.field}/> <button disabled={this.props.isWaiting} onClick={this.props.update}>Fetch</button> {this.props.isWaiting && <div>Waiting...</div>} </div> ); }}App.propTypes = { dispatch: React.PropTypes.func, field: React.PropTypes.any, isWaiting: React.PropTypes.bool};const reducer = (state = { field: 'No data', isWaiting: false }, action) => { switch (action.type) { case ActionTypes.STARTED_UPDATING: return { ...state, isWaiting: true }; case ActionTypes.UPDATED: return { ...state, isWaiting: false, field: action.payload }; default: return state; }};const store = Redux.createStore(reducer);const ConnectedApp = connect( (state) => { return { ...state }; }, (dispatch) => { return { update: () => { dispatch({ type: ActionTypes.STARTED_UPDATING }); AsyncApi.getFieldValue() .then(result => dispatch({ type: ActionTypes.UPDATED, payload: result })); } }; })(App);export default class extends React.Component { render() { return <Provider store={store}><ConnectedApp/></Provider>; }}

When the exported component is rendered, I can click the button and the input is updated correctly.

Note the update function in the connect call. It dispatches an action that tells the App that it is updating, and then performs an async call. After the call finishes, the provided value is dispatched as a payload of another action.

What is wrong with this approach? Why would I want to use Redux Thunk or Redux Promise, as the documentation suggests?

EDIT: I searched the Redux repo for clues, and found that Action Creators were required to be pure functions in the past. For example, here's a user trying to provide a better explanation for async data flow:

The action creator itself is still a pure function, but the thunk function it returns doesn't need to be, and it can do our async calls

Action creators are no longer required to be pure. So, thunk/promise middleware was definitely required in the past, but it seems that this is no longer the case?

https://codehunter.cc/a/reactjs/why-do-we-need-middleware-for-async-flow-in-redux

[releaseteam]

via Twitter https://twitter.com/releaseteam

[govindhtech]

Deep Dive Into API Connect IBM & Event Endpoint Management

API Connect IBM

APIs enable smooth system communication since real-time data processing and integration are more important than ever. IBM Event Automation‘s continued support of the open-source AsyncAPI specification enables enterprises to integrate the requirements for real-time events and APIs. This solution is made to assist companies create comprehensive event-driven connections while satisfying the increasing demand for efficient API management and governance. It also enables other integration systems to use Apache Kafka to ingest events with increased composability.

By combining IBM Event Automation and API Connect IBM, businesses can effectively handle API lifecycles in addition to Kafka events. The objective is to assist companies in developing robust event-driven architectures (EDA), which can be difficult because vendor neutrality and standards are required. Organizations are able to handle events, integrate systems, and process data faster in real time with IBM Event Automation, which helps to streamline this process.

Connecting events with APIs

Managing massive volumes of data created in real-time while maintaining flawless system communication is a challenge for organizations. Event-driven architectures and API-centric models are growing due to business agility, efficiency, and resilience. As businesses use real-time data increasingly, they need quick insights to make smart decisions.

Organizations are better able to respond to client demands and market shifts when they combine event streams and APIs to process and act on data instantaneously.

The complexity of managing a large number of APIs and event streams rises. Handling APIs and event streams independently presents a lot of difficulties for organizations, which can result in inefficiencies, poor visibility, and disjointed development processes. In the end, companies are losing out on chances to meet consumer needs and provide the best possible client experiences.

Organizations can manage and administer their APIs and events with a unified experience with the integration between Event Endpoint Management and API Connect IBM. Organizations are able to leverage real-time insights and optimize their data processing capabilities by combining API Connect and Event Endpoint Management to meet the increasing demand for event-driven architectures and API-centric data.

IBM API Connect

Important advantages of integrating IBM API Connect and IBM Event Automation

The following are the main advantages that an organization can have by utilizing the Event Endpoint Management and API Connect integration:

Unified platform for managing events and APIs

The integration eliminates the hassle of juggling several management tools by providing a unified platform for managing events and APIs. The cohesive strategy streamlines governance and improves operational effectiveness.

Improved visibility and monitoring

By receiving real-time data on API requests and event streams, organizations may better monitor and take proactive measures in management.

Enhanced governance

Sturdy governance structure that guarantees events and APIs follow organizational guidelines and regulations.

Efficient event-driven architecture

Improving customer experiences and operational efficiency by simplifying the development of responsive systems that respond instantly to data changes. Developing and implementing event-driven systems that respond instantly to changes in data is easier for organizations.

Scalability

Managing several APIs and Kafka events from a single interface that can expand along with your company without compromising management or performance.

Strong security measures

To guarantee safe data communication, combine event access controls in EEM with API security management.

Flexible implementations

Microservices, Internet of Things applications, and data streaming are just a few of the use cases that the integration supports. It is flexible enough to adjust to changing company needs and technology developments. Businesses can use the adaptability to develop creative solutions.

Developers within an organization that need to construct apps that use both events and APIs can benefit from the multiform API management solution that is offered by integrating Event Endpoint Management with API Connect IBM. Developers can find and integrate APIs and events more easily thanks to the unified platform experience, which also lowers complexity and boosts productivity. Developers can now create responsive and effective solutions that fully utilize real-time data by iterating more quickly and creating more integrated application experiences.

Think back to the retailer who wanted to streamline their supply chain. With APIs and events, a developer can build a responsive system that improves the effectiveness of decision-making. This integration gives the company the ability to enhance customer experiences and operational agility while also enabling data-driven plans that leverage real-time information. Real-time data enables businesses to promptly modify their inventory levels and marketing methods in response to spikes in consumer demand. This results in more sales and happier customers. This aids the company in staying one step ahead of its rivals in a market that is constantly changing.

API Management

An important step forward in efficiently managing APIs and event streams is represented by the integration of Event Endpoint Management and API connect, which will aid businesses in their digital transformation initiatives.

Read more on govindhtech.com