DEV Community: Fran Méndez 🍺

Status update (week 11, 2019)

Fran Méndez 🍺 — Thu, 14 Mar 2019 19:34:37 +0000

Olà amigos! This is an exciting week for us. Solace joined the AsyncAPI Initiative as a Platinum Sponsor 🎉. Thank you, Jonathan Schabowsky, for leading the process. And if that’s not enough, we finished our “Protocol mappings” milestone. Keep reading!

Latest changes in the specification

Protocol-specific information. This is a long-awaited feature. It allows you to define protocol-specific information in channels, operations, and messages.
Separate application headers from protocol headers. From now on, all the protocol-related headers must be included in a protocolInfo object, and the existing message headers must be used only for application headers, if any.
Annotate a channel parameter as multi-level. Do you want to tell your code a specific parameter should span across multiple levels? Now you can annotate channel parameters to indicate that. Pretty much like the # (pound) symbol in AMQP and MQTT or the > (greater than) symbol in NATS.
Unify examples fields. In the past, we had the example field in schemas and the examples field in some other places of the specification. They are now unified using the plural form and allowing for more than an example per object. However, we didn’t remove the support for example field in schemas, since we want to remain compatible with OpenAPI schemas.

Cumulative flow chart showing the progress of AsyncAPI 2.0.0.

Release report showing the planned and predicted end dates. We’re 38 days ahead of plan! 🔥

Donate

And last but not least, we’ve completed our first three weeks running the sponsorship campaign. We greatly appreciate the support from Solace and look forward to working together. You’ll hear more exciting news in the upcoming weeks. Stay tuned!

Remember, we’ve got different tiers so that everybody can show their love! ❤️

Donate here. Help Open Source projects.

“Give yourself permission to slow down. You can speed up by slowing down.”

— Gabby Bernstein

See you next week, folks! 👋

Event-Driven Architectures & AsyncAPI

Fran Méndez 🍺 — Thu, 26 Oct 2017 11:05:46 +0000

We, as engineers, often forget that APIs are not just HTTP APIs. We got so used to think about HTTP and REST APIs that we even have to stop for a moment to remember what the API term means. API stands for ”Application Programming Interface”. It’s exactly on the “Interface” piece where I want to focus. According to Oxford Dictionaries, an interface is:

A point where two systems, subjects, organizations, etc. meet and interact.

In software engineering, high-quality architectures always go hand in hand with well-defined interfaces and responsibility boundaries. Likewise, poorly-defined interfaces and boundaries are frequently the top reason for a bad design.

Event-Driven Architectures

When designing Event-Driven Architectures (EDA), you are also building APIs. These APIs will sit in the boundaries of your services and will allow them to communicate.

Topics and messages are first-class citizens because they precisely represent services interfaces. Consider the following example:

Email Service expects to receive a message on users/created topic. The message must contain information about the user's name and email, to be able to send a proper welcome email.

Can you imagine what happens if we change the Accounts Service and now it sends the message via the accounts/created topic? Or what if we change the message and now it specifies the email in an emailAddress field instead of email? In the first case, the message will never reach the Email Service so, you will not get an error, but the system will stop working correctly. In the second case, the message will be malformed from the Email Service point of view.

As you can see, topics and messages are the interfaces of our services, and so we have to care about them, especially as the number of services grows. We should pay attention in the same way we do with endpoints, and requests and response payloads in our HTTP APIs.

AsyncAPI

AsyncAPI provides a specification that allows you to define Message-Driven APIs in a machine-readable format. The spec is very similar to OpenAPI/Swagger so, if you’re familiar with them, AsyncAPI should be easy for you.

How does it work?

Your API definition consists of a file, or a set of them, where you define the topics, messages, servers, and more. You can afterward use the file(s) to create documentation, tooling or for whatever you need it.

Use cases

There are many use cases where AsyncAPI can be helpful, mostly to generate human-readable documentation and bootstrap code for your API. However, other use cases include:

Documentation-first development: Your API implementation doesn’t change unless you change its documentation.
API testing: Since you have all the API information, you could easily generate integration tests.
API management: You can build API management solutions gathering information from AsyncAPI files.
Monitoring: You can create tooling to help you monitor your APIs.

Getting started

A simple and straightforward way to get started with AsyncAPI is to play with the online editor. Though, if you’re in the mood for coding, take a look at the asyncapi.org website and tutorial.

Further resources

Introducing the AsyncAPI specification

Fran Méndez 🍺 — Tue, 23 May 2017 11:16:30 +0000

Originally posted on blog.hitchhq.com

We’re proud to launch an open-source initiative that we’ve been working on for months here at Hitch, the AsyncAPI specification. An OpenAPI-like specification for asynchronous APIs.

The AsyncAPI specification is protocol-agnostic, so you can use it for APIs that work over MQTT, AMQP, WebSockets, STOMP, etc. Basically, IoT APIs and asynchronous microservices.

The specification is heavily inspired on OpenAPI (aka Swagger) and it’s designed to maintain as much compatibility as possible with it.

Why another specification?

At Hitch we’re in love with API machine-readable documentation formats (OpenAPI, RAML, etc.). We always encourage our customers to use a machine-readable definition for their APIs because of its numerous benefits. From better documentation and code generation to scalable API support.
Internally, we use a message-driven microservices architecture and we couldn’t have all those tools that we have with the HTTP APIs. Things you get because you have your API defined with a machine-readable documentation format. And, on top of that, at the same time we noticed that some of our customers were creating IoT APIs over MQTT and they couldn’t get all the benefits from Hitch because the existing specifications don’t support message-driven APIs.

It was time to come up with something good enough for everyone instead of having every company fighting its own battle. We can learn a lot together if we join forces. Let’s start!

A basic example

Email service

This example describes a very basic email service. It sends an email every time a new user signs up. It subscribes for the hitch.accounts.1.0.event.user.signup event and, when received, sends the email and publishes a new message notifying the system that the email has been sent.

asyncapi: '1.0.0'
info:
  title: 'Sign up email example'
  version: '1.0.0'
baseTopic: 'hitch'
host: 'asyncapi.hitchhq.com'
schemes:
  - 'amqp'
  - 'mqtt'

topics:
  accounts.1.0.event.user.signup:
    subscribe:
      $ref: '#/components/messages/userSignedUp'
  email.1.0.event.email.sent:
    publish:
      $ref: '#/components/messages/emailSent'

components:
  messages:
    emailSent:
      summary: 'Email sent to user.'
      description: 'A message notifying an email has been sent.'
      payload:
        type: 'object'
        properties:
          user:
            $ref: '#/components/schemas/user'
          content:
            $ref: '#/components/schemas/content'

    userSignedUp:
      summary: 'A user has signed up.'
      payload:
        type: 'object'
        properties:
          user:
            $ref: '#/components/schemas/user'
          signup:
            $ref: '#/components/schemas/signup'
  schemas:
    content:
      title: 'content'
      description: 'The email content'
      type: 'string'
    id:
      title: 'id'
      description: 'Resource identifier'
      type: 'string'
    username:
      title: 'username'
      description: 'User handle'
      type: 'string'
    datetime:
      title: 'datetime'
      description: 'Date and Time of the message'
      type: 'string'
      format: 'date-time'
    user:
      type: 'object'
      required:
        - 'id'
        - 'username'
      properties:
        id:
          description: 'User Id'
          $ref: '#/components/schemas/id'
        full_name:
          description: "User's full name"
          type: 'string'
        username:
          $ref: '#/components/schemas/username'
    signup:
      type: 'object'
      required:
        - 'method'
        - 'datetime'
      properties:
        method:
          description: 'Signup method'
          type: 'string'
          enum:
            - 'email'
            - 'facebook'
            - 'twitter'
            - 'github'
            - 'google'
        datetime:
          $ref: '#/components/schemas/datetime'

If you are familiar with the OpenAPI specification I’m sure you already found lots of similarities. But, what’s this topics section in the code? And what's this accounts.1.0.event.user.signup? Let's dive into it.

Core concepts

The AsyncAPI specification is based on the assumption of two core concepts:

Messages

The way consumers can communicate with your API is based on messages. A message is a piece of information two or more programs exchange. Most of the times to notify the other end(s) that, either an event has occurred or you want them to perform an action.

Technically speaking the events and actions will always be sent in the same way. These are just messages and their content can be anything. So when we speak about the difference between events and actions, this is just a semantic differentiation of the content of the message. We do not enforce you to make any difference between them (although we encourage you to do it).

Martin Fowler’s talk on event-driven architectures at GOTO
A message can contain headers and a payload, however both are optional. To remain as much protocol-agnostic as possible, the specification allows you to define any kind of header.

Topics

Message-driven protocols usually contain something that can be found as a topic (MQTT), routing key (AMQP), destination (STOMP), etc. To some extent, they can compare to URLs in HTTP APIs. So when you send a message to your API it will be routed depending on the topic you published it on. It allows you to create APIs that subscribe to certain topics and publish to other ones.

There’s no standard way of naming topics so we recommend you to have a look at our proposal here.

Tooling

Code generators

So far we only have a code generator for Node.js (github.com/asyncapi/node-codegen). We would like to have you involved in generating one for your programming language of choice.

Documentation generators and API support

Are you interested in generating documentation for your AsyncAPI and/or setting up the Hitch API Assistant? We can definitely help! Drop us a line at hi@hitchhq.com and we’ll get back to you.

Conclusions

The AsyncAPI specification will let us improve the interoperability and tooling around this type of APIs. Either it’s for the Internet of Things or for internal asynchronous microservices, we believe this will make the difference in the future of async APIs.