DEV Community: Bump.sh

JSON Streaming in OpenAPI 3.2

Bump.sh — Tue, 02 Sep 2025 14:04:35 +0000

Streaming data allows API servers to send and receive data in real-time or in chunks, rather than waiting for the entire response to be ready. This is already how browsers handle HTML, images, and other media, and now it can be done for APIs working with JSON.

This can improve responses with lots of data, or be used to send events from server to client in realtime without polling or adding the complexity of Webhooks or WebSockets. Streaming works by sending "chunks", which clients can then work with individually instead of waiting for the entire response to be ready.

Streaming JSON in particular is increasingly useful as expectations around big data, data science, and AI continue to grow. JSON on its own does not stream very well, but a few standards and conventions have popped up to expand JSON into a streamable format, and OpenAPI v3.2 introduces keywords to describe data in these stream formats.

JSON Streaming

Streaming JSON is a bit tricky because JSON is not designed to be streamed. A naive approach might look like this:

{
  {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"},

This would trip up most tooling (because the closing bracket is not present in the payload), but we can use something like JSON Lines (a.k.a JSONL) to send one JSON instance per line.

{"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
{"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Hows it hangin?"}
{"timestamp": "1985-04-12T23:20:53.29Z", "level": 1, "message": "Bye!"}

This format allows each line to be a valid JSON object, making it easy to parse with standard native tooling and a for loop. There are a bunch of other streaming formats you might want to work with in your API like Newline Delimited JSON (NDJSON), JSON Text Sequence, GeoJSON Text Sequence. Thankfully they are all quite similar and working with them in OpenAPI is almost identical.

Streaming with OpenAPI

OpenAPI v3.0 & v3.1 were able to stream binary data, but struggled to support JSON streaming formats as there was no standard way to define the schema of individual events in a stream. People would try to describe things as an array:

content:
  application/jsonl:
    schema:
      type: array
      items: 
        type: object
        properties:
          timestamp:
            type: string
            format: date-time
          level: 
            type: integer
          message:
            type: string

You might see this sort of thing around, but it's not valid, and will confuse tooling. A stream cannot be described as a single array, and it is a sequence of multiple objects on new lines which is rather different. Some tools could spot the application/jsonl content type and figure that out, but we don't need awkward hacks anymore because the OpenAPI team have solved the problem.

OpenAPI v3.2 introduces two new keywords to describe streamed data and events:

itemSchema - define the structure of each item in a stream.
itemEncoding - define how those items are encoded (or serialized), as text, JSON, binary, etc.

itemSchema

Describing a stream with itemSchema works just like schema with one difference: it will be applied to each item in the stream, instead of the entire response.

Consider an example like the train travel API running a stream of tickets:

HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: application/jsonl; charset=utf-8
Transfer-Encoding: chunked
Date: Tue, 19 Aug 2025 18:36:10 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"train":"ICE 123","from":"Berlin","to":"Munich","price":79.9}
{"train":"TGV 456","from":"Paris","to":"Lyon","price":49.5}
{"train":"EC 789","from":"Zurich","to":"Milan","price":59}

To describe this stream of items, we can use the itemSchema keyword:

content:
  application/jsonl:
    itemSchema:
      type: object
      properties:
        train:
          type: string
        from:
          type: string
        to:
          type: string
        price:
          type: number
          format: float

Tooling now has two important switches it can use to figure out how to handle the response. The itemSchema makes it clear the response is a stream, and the application/jsonl content type lets tooling decide how to present that.

For streaming formats that just handle streams of JSON, the itemSchema is often sufficient to describe the structure of each item in the stream. For more complicated formats, additional encoding information may be needed.

itemEncoding

The itemEncoding keyword allows you to specify how each item in the stream should be encoded, with the same encoding object as the encoding keyword.

Using itemEncoding is only possible for multipart/* responses, so it is not very useful for an API that's streaming JSON, unless you were streaming a mixture of JSON and assets/images on a single response.

content:
  multipart/mixed:
    itemSchema:
      $comment: A single data image from the device
    itemEncoding:
      contentType: image/jpg

Let's ignore itemEncoding for now and focus on the major use case of streams for APIs: streaming data and events.

Popular Streaming Formats

They all work a little different, but they share the common goal of allowing data to be sent in a continuous stream rather than as a single, complete response.

JSON Lines & NDJSON

Working with JSON Lines or NDJSON is basically identical in OpenAPI, and feels very much like working with plain JSON responses just with a different header and a bit of itemSchema usage.

If using JSONL use content type application/jsonl, and if using NDJSON use content type application/x-ndjson.

paths:
  /logs:
    get:
      summary: Stream of logs as JSON Lines
      responses:
        '200':
          description: |
            A stream of JSON-format log messages that can be read
            for as long as the application is running, and is available
            in any of the sequential JSON media types.
          content:
            application/jsonl:
              itemSchema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: date-time
                  level:
                    type: integer
                    minimum: 0
                  message:
                    type: string
              examples:
                JSONL:
                  summary: Log entries
                  description: JSONL examples are just a string where each line is a valid JSON object.
                  value: |
                    {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
                    {"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Hows it hangin?"}
                    {"timestamp": "1985-04-12T23:20:53.29Z", "level": 1, "message": "Bye!"}

The example once again shows JSONL as a series of JSON objects with a newline character \n (0x0A) between them. This can only be described as a YAML multiline string, because JSONL/NDJSON cannot be described as plain JSON/YAML due to the newline characters.

Remember to use value: | to write multi-line strings in YAML, because the pipe will allow newlines to be passed through. Using value: > would remove newlines and put each JSON instance onto the same line.

The sample code for either of these formats could look a bit like this:

app.get("/tickets", async (_, res) => {
  res.setHeader("Content-Type", "application/jsonl; charset=utf-8");
  res.setHeader("Transfer-Encoding", "chunked");

  for (const ticket of tickets) {
    res.write(JSON.stringify(ticket) + "\n");
  }

  res.end();
});

JSON Text Sequence

A third JSON streaming format which would be identical other than a weird little complication. The other two formats are just a newline character \n (0x0A) at the end of the line, but RFC 7464: JSON Text Sequence requires a control character at the start ASCII Record Separator (0x1E). This is not a visible character in most contexts, but it will be in there like this:

0x1E{"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
0x1E{"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Hows it hangin?"}
0x1E{"timestamp": "1985-04-12T23:20:53.29Z", "level": 1, "message": "Bye!"}

The 0x1E (ASCII Record Separator) indicates the start of a new JSON object in the stream. Control characters are a bit magical and invisible to most text editors so it can be a little confusing. Working with JSON Text Sequence tooling for both producing the stream and reading the stream can solve this problem, letting the tooling insert and read out the control characters without you needing to worry.

import { Generator } from "json-text-sequence";

// ... snip express setup ...

app.get("/tickets", async (_, res) => {
  res.setHeader("Content-Type", "application/json-seq");

  const g = new Generator();
  g.pipe(res);

  for (const ticket of tickets) {
    g.write(ticket);
  }

  res.end();
});

The json-text-sequence package makes this easier and provides a simple method for generating and consuming JSON Text Sequences.

Server-Sent Events (SSE)

Streaming JSON as chunks of data is only one way that JSON gets streamed. What about sending events, with some JSON being passed along as attributes?

Server-Sent Events (SSE) can handle this, as a standard for sending real-time updates from a server to a client over HTTP. In OpenAPI, you can define SSE streams using the text/event-stream content type and the itemSchema keyword to describe the structure of the events being sent.

content:
  description: A request body to add a stream of typed data.
  required: true
  content:
    text/event-stream:
      itemSchema:
        type: object
        properties:
          event:
            type: string
          data:
            type: string
          retry:
            type: integer
        required: [event]
        # Define event types and specific schemas for the corresponding data
        oneOf:
        - properties:
            event:
              const: addString
        - properties:
            event:
              const: addInt64
            data:
              format: int64
        - properties:
            event:
              const: addJson
            data:
              contentMediaType: application/json
              contentSchema:
                type: object
                required: [foo]
                properties:
                  foo:
                    type: integer

The oneOf is optional, but a handy use of polymorphism to describe different schemas for each event - which can really help with documentation and validation.

Valid events to come through this stream might look like:

event: addString
data: This data is formatted
data: across two lines
retry: 5

event: addInt64
data: 1234.5678
unknownField: this is ignored

event: addJSON
data: {"foo": 42}

Sentinel Events

Some streaming systems do not always send all data or events in the exact same way. The items in a stream could be polymorphic objects, or there could be some special events that come through to say the stream is closed (also known as sentinel events).

Instead of trying to handle all of these edge cases with special new keywords, OpenAPI allows you to use the standard JSON Schema keywords to model these variations.

text/event-stream:
  itemSchema:
    oneOf:
    - <your normal data/event schema>
    - const: { data: "[DONE]" }

Whatever the schema is, it can be defined using the standard JSON Schema keywords like oneOf, anyOf, or allOf to handle variations in the event structure. This allows you to define a flexible schema that can accommodate different types of events in the stream.

Conclusion

We're excited for OpenAPI v3.2 to launch (hopefully any time in the next few weeks?) and we're working hard to get Bump.sh ready to support as much of the new functionality as possible. Let us know in the comments what features you're looking forward to, and share any ideas you have for how we can improve our support for streaming JSON in APIs.

OpenAPI 3.1 - The Cheat Sheet

Bump.sh — Wed, 18 Sep 2024 15:09:40 +0000

We can't tell you how stoked we are about this. It's been a while that we realized something key was missing, to help the entire community adopt and use OpenAPI daily.

Something short enough, while thorough enough, so that you always make sure you always completely describe your API, without missing any crucial information, nor wondering "Hugh... How do I write this again?" and having to scan through the entire specification.

Something you could even hold in your hands. Because, yes, as much as we avoid printing things on a day-to-day basis, sometimes screens are not enough. Teachers, rest assured: our cheat sheet print-outs are too large to be hidden in your students pockets.

Anyway, that's it, we made it. Let us introduce the OpenAPI 3.1 Cheat Sheet.

Download the PDF version

It took us about 6 months to produce this first version. First of all, because we're of course quite busy developing Bump.sh and serving our customers. But more importantly, because synthesizing OpenAPI on an A4/US letter sheet is just not trivial.

The Specification covers a wide range of use cases. It is robust in the sense that your APIs can be completely described, so that humans and machines alike can discover it, and interact with it. In the end, an OpenAPI contract can become quite deep and complex. We wanted to squeeze the essence out of it, and brainstormed multiple times about what should be in (and how), and what should be out.

You'll read it on your own, but here are the sections we retained:

We had a chance to work on this with OpenAPI experts (👋 Phil Sturgeon, James Higginbotham and Kin Lane, as well as some of our key power users at Elastic, Lightspeed Commerce, and many more).

And we wanted to make the outcome of that work accessible completely for free, as the entire OpenAPI community should benefit from it, free of charge. It is CC BY-NC-SA 4.0 licensed.

To be honest and transparent, this is a first version of that Cheat Sheet. We might have been a little too enthusiastic to print it for apidays London 2024. Fetch your exclusive sample there: there won't be many, and we'll have to print new versions for Paris as we've already spotted some typos.

They're fixed in the downloadable PDF version, but if you have a hard copy and spot those errors, we're paying a drink to the first 5 people who drop by our booth with the full list of errors.

This Cheat Sheet will be lively in the coming weeks and months. We'll work on:

improving the current version
making a web version of it
covering the next versions of OpenAPI (Moonwalk, we see you)
making one for AsyncAPI

Share it with your network, the person working next to you or the world via social media; it's built for that!

An AsyncAPI Example: Building Your First Event-driven API

Bump.sh — Tue, 19 Sep 2023 08:44:20 +0000

Event-driven APIs are APIs that use events to enable real-time and asynchronous communication between different components of a system. This leads to a couple significant benefits right out of the gate:

Clients receive real-time updates without constantly polling the server, which improves user experience.
System components can communicate without being directly connected to each other, so API producers and consumers can be more loosely coupled.

Why Use Event-driven APIs?

Let’s break those two ideas down a bit so you can really see what’s going on.

An event is any change in state or an update that a client might be interested in, like a new user registration or an update in the payment status of a transaction. In an event-driven system, a component known as the publisher sends an event to a message broker. The message broker sends the event to all the other components, known as subscribers, that have registered to receive that particular event. This allows the components of the system to communicate in real-time without being directly connected to each other.

As an example, picture a chat application. When a user sends a message, an event-driven API can immediately notify all the other users in the chat, allowing the message to display in their chat window without needing to refresh the page. In a traditional synchronous API, the client would need to poll the server to check for new messages very often and then update the user. With event-driven APIs, clients receive real-time updates from the API without constantly polling for changes, making them more efficient when it comes to network resource usage.

In a traditional synchronous request-response API, the components are tightly coupled. The consumer must make a request to the provider to receive data (say, for example, polling for new messages in a chat application). In an event-driven API, the components are decoupled. The publisher sends events to the message broker, which then broadcasts the events to the subscribers. The separate components can be more independent and flexible, since they don’t rely on direct communication with each other.

However, in order for the system to work effectively, there must be a common understanding between the components regarding events and their data structures. This is where AsyncAPI comes in; it helps define a contract that describes how the components communicate and behave effectively.

Let’s walk through the process of implementing an event-driven API using AsyncAPI, a specification for defining asynchronous APIs. We’ll also introduce Bump.sh, a tool for documenting and tracking event-driven APIs lifecycle/changes, and demonstrate how you can use it in conjunction with AsyncAPI files.

Implementing a Node.js Event-Driven API with AsyncAPI

AsyncAPI is a specification for defining the structure and behavior of event-driven APIs. It’s similar to OpenAPI, a specification for defining REST APIs.

However, AsyncAPI has specific features for defining the events and subscriptions of an event-driven API. It provides a standardized way to describe the events, channels, and message formats used in an asynchronous API, making it easier for developers to understand and use that API.

Before we begin the process of implementing a Node.js event-driven API described using AsyncAPI, there are a few prerequisites that you will need to have installed:

Node.js
Git
Optional: Mosquitto, an open-source message broker that implements the MQTT protocol; this tutorial uses the public test server

Once you have these installed, you can follow the steps below to implement your event-driven API.

1. Create an AsyncAPI File

First, create an AsyncAPI file. This will define the events and their corresponding data that you’ll use in your event-driven system. It also defines the structure and behavior of your asynchronous APIs.

AsyncAPI files are written in YAML or JSON and follow a specific format defined by the AsyncAPI specification. An AsyncAPI file consists of several main components:

asyncapi: Specifies the version of the AsyncAPI specification that the file follows; at time of writing, the latest available is v2.6.0, which is what this tutorial uses.
info: Contains metadata about the API, such as the title, the version or the description of your API.
servers: Lists the servers that the API is available on, along with the protocol and any additional configuration required to use the server. In our testing API, that will be the network location of our message broker.
channels: Defines the channels that the API exposes, along with the operations that can be performed on each channel.
components: Defines reusable components that can be used throughout the AsyncAPI file, such as message payloads and security schemes. This section is optional, as you can define these components directly, but I do recommend it. As your AsyncAPI definition file starts to grow, this helps you avoid repeating yourself (e.g., when a message format is used in multiple channels).

The snippet below defines the first part of the AsyncAPI file for a chat application. It covers the general application descriptions:

asyncapi: 2.6.0
info:
  title: Chat Application
  version: 1.0.0
servers:
  testing:
    url: test.mosquitto.org:1883
    protocol: mqtt
    description: Test broker

This AsyncAPI file defines a chat application using the AsyncAPI 2.6.0 version.

It also defines the servers block that specifies the network location of your message broker. The API application defined here uses the MQTT protocol and is available on the testing server at test.mosquitto.org:1883. This URL is a publicly available Mosquitto broker for test purposes; feel free to replace it with a local URL if you have Mosquitto installed on your environment.

The following section defines the channels available within the API. It defines the different operations the chat application can perform and their payloads.

channels:
  chat:
    publish:
      operationId: onMessageReceieved
      message:
        name: text
        payload:
          type: string
    subscribe:
      operationId: sendMessage
      message:
        name: text
        payload:
          type: string

The channels section defines all the channels that the API exposes. In this case, there is a single channel called chat that exposes a publish and subscribe operation. The publish method allows clients to send messages to the chat application via the chat channel, while the subscribe method allows users to receive messages from the chat channel.

This might seem a bit counterintuitive as there are two sides to think about, the server application and the client. Instead, think about it this way: publish events are sent from the client to the application, while subscribe events are sent from the application to the clients.

Read more about pub-sub semantics here, then check out this proposal that aims to resolve the confusion between publish and subscribe events.

In the case of this tutorial, both operations have a very simple message payload of type string, which defines the text to be sent on the message. However, the message could be more complex and in this case described with JSON schema.

You can review and copy the full file here.

2. Generate the Application Code with AsyncAPI Generator

After creating your AsyncAPI file, you can use the AsyncAPI Generator to automatically generate the code for your event-driven application. The AsyncAPI Generator is a command-line tool that can generate code in multiple languages, including JavaScript, Python, and Go.

To use the AsyncAPI Generator, you will first need to install it using npm:

npm install -g @asyncapi/generator

Once you have installed the AsyncAPI Generator, you can use it to generate the code for your event-driven application.

The generated code is meant to be a starting point, not a comprehensive build-and-use solution.

The following command generates a functional node application from your AsyncAPI file. Make sure to replace the file and server names where appropriate.

ag asyncapi.yaml @asyncapi/nodejs-template -p server=testing  -o example

This command tells the AsyncAPI generator to generate Node.js code using the asyncapi.yaml file that you created in the previous step. The generator will generate the code for the testing server we have just defined with our AsyncAPI file, and output those new files to a folder named example. The AsyncAPI Generator supports code generation in many different languages such as Node, Java, Python, and Go.

After running the command, you should have a full-fledged node application powering your event-driven application.

You can run the following to install the dependencies and run the application.

npm install
npm start

You should see the following output:

> node src/api/index.js

 SUB  Subscribed to chat
 PUB  Will eventually publish to chat
Chat Application 1.0.0 is ready!

🔗  MQTT adapter is connected!

3. Test the AsyncAPI Node.js Application

To test the application, you need to send messages to the broker as a publisher. You can do this using the MQTT.js library. Install it by running the following command in a separate terminal window:

npm install mqtt -g

Run the following command to send a message to the message broker. This command sends a publish command to the test broker on the chat channel defined in your AsyncAPI file.

mqtt pub -t 'chat' -h 'test.mosquitto.org' -m "Hello World"

After running this command, check the original window running the chat application, and you should see the following output:

← chat was received:
'{text: Hello World}'

This output means your application successfully received your message from the message broker. If you want to start implementing business logic, you can review the code in the example directory.

You will find the handler for the messages under examples/src/api/handlers/chat.js. The file should look like this:

const handler = module.exports = {};

/**
 * 
 * @param {object} options
 * @param {object} options.message
 */
handler.onMessageReceieved = async ({message}) => {
  // Implement your business logic here...
};
/**
 * 
 * @param {object} options
 * @param {object} options.message
 */
handler.sendMessage = async ({message}) => {
  // Implement your business logic here...
};

Using Bump.sh with AsyncAPI

By creating your AsyncAPI file, you actually also created an API contract ! You can read all about them here but in short, an API contract specifies the components and describes the behavior of an API, for instance available events and data or the rules for using the API.

You saw this earlier with the chat application implementation; you had to define the different channels as well as the operations that a client could perform on each channel.

Having a clear and formal API contract can ensure that the different components of an event-driven system can communicate and work together effectively. It can also make it easier to collaborate with other developers and teams, since everyone will have a clear understanding of the API and how it’s working.

You can use Bump.sh to document and keep track of the changes in your event-driven API via its AsyncAPI API contract.

To use Bump.sh and generate your AsyncAPI based documentation, simply create an account. Then you can simply drag and drop your AsyncAPI file in the onboarding flow.

After signing up, fill out the following form with the details of your API:

You can then proceed to upload your AsyncAPI file manually or using Bump.sh CLI.

To upload your file using the CLI start by installing it:

npm install -g bump-cli # using npm
yarn global add bump-cli # using yarn

Then preview your generated API documentation by running :

bump preview path/to/file.json/yml

The CLI will respond with an URL that, if visited, will let you visualize for a few minutes how your API documentation would render in Bump.sh.

When your AsyncAPI file is ready to be deployed, you can follow the simple steps of the Getting Started to have your API documentation live and ready to share.

You can also connect the Bump.sh CLI to CI/CD tools, and there is even a GitHub Action you can add to any project. Which will allow you to automatically track and inform about API changes and deploy new versions of your API, among other cool possibilities you can read about on the Bump.sh page in GitHub marketplace

Conclusion

Event-driven APIs lead to real-time, responsive, and loosely-coupled systems, and AsyncAPI is a great way to define those APIs. By using AsyncAPI and Bump.sh together, you can create high-quality documentation for all your event-driven APIs.

Feel free to reach out to us if you have feedback, comments, or suggestions you’d like to share!

AsyncAPI vs. OpenAPI: Which Specification Is Right for Your App?

Bump.sh — Thu, 03 Aug 2023 16:45:00 +0000

Depending on how your application is designed and what it needs to accomplish, you probably want to consider choosing one type of communication protocol for your API over another—namely, synchronous or asynchronous. And which protocol you use determines which specification you need to follow for your API—OpenAPI or AsyncAPI.

Let’s take a brief look at the differences between synchronous and asynchronous APIs, and then we’ll talk about whether OpenAPI or AsyncAPI is best for communicating the ins and outs of your API to your users.

Synchronous vs. Asynchronous APIs

Synchronous and asynchronous APIs differ mainly in how they process information.

Synchronous APIs respond to each client request with only minimal elapsed time, and clients must wait for the response before code execution can continue. This is the type of API that supports most of the internet, and they typically use the REST protocol.

Asynchronous APIs may provide a callback or notification when requested resources are ready, allowing clients to continue functioning without tying up resources waiting for a response from the API. These APIs use pub-sub messaging queues like MQTT and RabbitMQ, data streams like Kafka, or bidirectional communication protocols like WebSockets. IoT devices also commonly use asynchronous APIs.

Choosing Between OpenAPI and AsyncAPI

Documentation of your APIs is critical for communicating between backend and frontend developers. And good documentation can go beyond just improving the development experience - it can even increase adoption of your API.

Industry-standard specifications like OpenAPI and AsyncAPI ensure that you’re effectively communicating to your users how they can interact with your API through an API contract. Which spec you use to define and document your API depends on your use case, available resources, engineering team and community support, and chosen protocol to transmit data.

In general, synchronous APIs can be defined using the OpenAPI standard, and asynchronous APIs can be defined using the AsyncAPI standard.

Protocols

OpenAPI is typically used for RESTful APIs, which leverage HTTP or HTTPS as a transport protocol for data. The client makes a request to the server, which responds quickly (ideally within milliseconds or seconds). HTTP is mostly used as a unidirectional protocol, meaning the connection is closed after a single request and response. Each request must create a new connection to the server.

To receive updates on any server changes, the client must rely on polling. Since the application does not know when a task will be completed, it must continue calling the API until the update is detected.

AsyncAPI is based on event driven architectures (EDA). In this context, the sender and recipient don’t have to wait for a response from the other to do their next task or request.

In event driven architectures, as you might have guess, it all revolves around events. An event is defined as a change of state.
In an EDA, when an change of state occurs, the producer captures that event and sends it to all consumers who have subscribed to this event. There can be a broker in the middle in some cases. This way of architecturing APIs is refered to as Asynchronous.

Asynchronous APIs can use bidirectional protocols, where a connection is maintained until it’s terminated by either the client or the server. Communication protocols like WebSockets allow the application to request data from the server but continue other processing while it waits for the response. Once resources are available to generate the response, the API produces a response, and the WebSocket connection streams the information back to the application.

Applications can also subscribe to a channel on a message broker like MQTT, Kafka, or RabbitMQ where they can receive updates or notifications as events occur. When updates are no longer needed, the subscription can be terminated.

A single API can make use of multiple protocols. We’ll talk more about that in a bit, but for now, suffice it to say that an API can combine synchronous and asynchronous methodologies, as well as use multiple asynchronous protocols. GraphQL APIs, for example, send queries over HTTP (a synchronous protocol), but also provide asynchronous messaging with WebSockets.

Simplicity of Implementation

Since OpenAPI and AsyncAPI support different communication protocols, they require different skills to implement and different amounts of work as well.

To implement an API designed according to OpenAPI, developers can use web application frameworks to set up the actual API. Authentication is also built into the standard, so everything needed to create your synchronous API is present once your OpenAPI document is created. Since synchronous APIs send messages directly to the endpoint, there’s no additional architecture required to build the API.

On the other hand, implementing an asynchronous API is more complicated. Developers can still use web application frameworks, but they do need more architecture support than that. If your API uses a message broker as a middleman between application and API, that needs to be designed and built. If you’re using WebSockets to push notifications, both the server and the application need listener functions that keep the connection open.

Community Support

AsyncAPI and OpenAPI are both open-source standards and part of the Linux Foundation. Both are stable, well-maintained specifications and should be supported well into the future. Still, there are a handful of differences when it comes to their ecosystems.

OpenAPI is a more established standard, since it was developed for synchronous REST APIs. The OpenAPI specification has many contributors from the Linux Foundation and the community. Many more have contributed to the standard through discussion and examples. The governance model of the OpenAPI Initiative allows both community and industry contributions in an effort to keep the specification vendor-neutral. To contribute, you must meet requirements for membership in the initiative.

AsyncAPI is a newer standard based on OpenAPI. While it has fewer code contributors than OpenAPI, its popularity is quickly growing. AsyncAPI attributes its rising success to its community support and all the hosted tools related to AsyncAPI. In late 2020, AsyncAPI also formed an open governance model to assure the community that no single company has control over AsyncAPI and that this initiative is, in fact, community driven. They even are a Linux Foundation Project since 2021.

Use Cases

Now, as we’ve already mentioned, whether you would use OpenAPI or AsyncAPI specification depends on what protocols your API uses. Which protocol you use depends on your specific use case and what backend resources are available for support. In general, OpenAPI is used to define APIs that provide immediate feedback (synchronous). The AsyncAPI spec defines APIs that don’t need to respond immediately to a request (asynchronous).

But let’s see how that works out in some everyday use cases. When does one implementation have an advantage over the other?

RESTful APIs

REST is a software architecture style commonly used to support APIs used on the web, and as mentioned earlier, synchronous APIs carry the day here. These are simple, uniform interfaces that are often used to support cloud applications and cloud services because they’re stateless, consistently available, and widely accessible. With these traits, a RESTful API can provide information on virtually any topic easily and reliably.

Internet of Things

Internet of Things (IoT) devices need to handle inconsistent communications between the device and the API. For example, an IoT device may go out of internet range periodically, but will still need to send data to the API for processing. This means that data may be sent in bursts to the API when a connection is available. IoT devices may also need to notify the API when a significant event has occurred, as when a smoke alarm goes off or a camera detects motion.

As a result of event processing, an IoT device may need to receive asynchronous notifications from the server. While the device itself holds raw data, servers collect and perform calculations of the data over time. The server may need to send notifications to the device when an event has occurred, like an IoT device losing power in your home.

Combining Synchronous and Asynchronous APIs

Many SaaS API offerings exist to set up shopping carts for users and store inventory management for owners. These solutions tend to include a mixture of synchronous and asynchronous APIs.

Inventory management applications, for example, use asynchronous API resources that allow users and owners to retrieve information about available inventory, user accounts, and pricing. Business owners can update their inventory, and it's automatically available to users when the API pushes data to the message broker. However, remember that synchronous APIs support most of the internet. An online retail shop may very well want the reliability of a RESTful API as part of its system to facilitate communication with a wide array of other organizations and developers.

Documenting in Any Case

Regardless of which specification you choose to develop your API with, users need to be aware of new features and changes. Maintaining your API’s documentation and ensuring that it keeps to the standards of your spec can be a time-hungry task.

Bump.sh transforms your OpenAPI and AsyncAPI documents into beautiful documentation. It lets your developers focus on building products rather than maintaining docs. Bump.sh provides automatic change detection by integrating with CI tools, pushing notifications of the change to stakeholders, and enabling validation via its simple-to-use interface. Take its free trial for a spin to see how Bump.sh can make documenting any API - OpenAPI or AsyncAPI - simple. You can also try any AsyncAPI or OpenAPI file in the preview at the bottom of this page.

So… Which one to pick?

To summarize, the API specification you should use depends entirely on what type of API you want to build. Long story short, synchronous APIs use simple, direct endpoint communication to link a client to a server. When data consists of simple requests that can be completed by the server quickly, a synchronous, RESTful API that follows the OpenAPI specification is what you want.

Asynchronous APIs use message brokers or pub-sub to communicate between server and application as data is made available. They’re useful for real-time applications that require frequent updates. They can be more complex to implement since they require more architecture than synchronous APIs, but you can stay organized thanks to the AsyncAPI specification.

Both OpenAPI and AsyncAPI are open-source specifications and provide a standard method for designing and implementing APIs. A key asset of both specs is the ability to create comprehensive, industry-standard documentation for your API. By connecting your documents to Bump.sh, you can rest assured that your documentation is automatically updated for each API release.

Author: Joanna Wallace

Creating an API with Express.js using OpenAPI

Bump.sh — Mon, 24 Jul 2023 12:06:00 +0000

Express is a popular backend JavaScript framework for building landing pages and integrated content management systems or integrating APIs with other tools. With over twenty million weekly downloads on npm at the time of writing, the framework's popularity comes from its ease of setup and use, extensibility with first- and third-party middleware functions, and its flexible built-in router.

OpenAPI is a standard for describing HTTP APIs in a document that humans and computers alike can understand or consume. Building APIs according to the OpenAPI specification can ease friction between an API's developer and its consumers, especially in terms of how the API should operate. Some knowledge about the OpenAPI specification can definitely help you understand the examples provided.

In this article, you'll learn how to build REST APIs using Express. You'll also learn how to document your APIs according to the OpenAPI specification with express-openapi. Finally, you'll learn how to effectively manage your API documentation using Bump.sh.

Crash Course in Express

The Express architecture is based around middleware, which are functions that can access and modify the request and response object and either return a response or trigger subsequent middleware functions. Middleware can be registered by invoking the .use() method on an Express application, like so:

import express from 'express';
import middlewareFunction from 'my-middleware-function';

const app = new express();

app.use(middlewareFunction);

Express has three built-in middleware functions for serving static files (express.static, parsing JSON (express.json) and URL-encoded request payloads (express.urlencoded). Together with the Express router, these provide a good starting point for most applications.

The Case for OpenAPI

The OpenAPI specification is an opinionated, language-agnostic standard for describing HTTP APIs that allows humans and machines to understand and interact with an API without the need to access the source code. A valid OpenAPI description document is also called an API contract because, like a contract, it enforces a specific behavior that must be implemented by the developer and adhered to by the consumer.

An API contract adds value in many ways, including easing the development burden, improving ease of adoption for first-time consumers, and using automated tools to reduce the amount of work needed to generate client code and documentation or validate I/O data.

In the next few sections, we'll see API contracts in action as we build an Express application and generate documentation with Bump.sh.

Implementing an API with OpenAPI and Express

In this section, using Express, you'll build an API that follows the OpenAPI specification. You will be walked through steps to set up an Express application, configure it according to the OpenAPI spec, and see how to view your API documentation.

Prerequisites

In order to follow along with this tutorial, you'll need the following:

Familiarity with JavaScript (and Node.js)
Node.js
A Node.js package manager — npm was used in this article
A Bump.sh account

You can find the source code for the project in this GitHub repo.

Creating an Express Application

Let's start with creating an Express application. As mentioned, one of the reasons Express is so popular is that it's quick and easy to set up.

First, create a new folder for your project. Spin up a terminal session and run the following command to create a folder named express-oas:

mkdir express-oas

Next, initialize a JavaScript project by adding a package.json file. Using the same terminal session or via your computer's file manager, create a file named package.json:

cd express-oas
touch package.json

Open the package.json file using a text editor, then copy and paste the following in the file:

{
  "name": "express-oas",
  "main": "index.js",
  "scripts": {},
  "dependencies": {
    "express": "^4.18.2"
  }
}

You can also use npm init or yarn init to automatically generate a package.json file. Both npm init and yarn init (on Yarn Classic) run interactively, meaning that you'll need to respond to a series of prompts before the file is generated. To skip these prompts and use the defaults, you can run the command with the -y flag:

# Run interactively
npm init

# Run non-interactively
npm init -y

Finally, install the express package dependency from the npm or yarn registry and create your Express application.

In your terminal, run the command to install dependencies:

npm install

Next, create a file named index.js in your project's root folder. You can do that via the terminal by running the following:

touch index.js

Open this file using your text editor, then import and initialize your Express application:

import express from 'express';

const PORT = 3000;

const app = new express();

app.use(express.json());

app.listen(PORT, () => {
    console.log(`Server running on ${PORT}`);
});

The default export from the express package is a function that, when invoked, creates an express application instance. This instance or object contains methods for routing HTTP requests, configuring middleware, and binding and listening for connections on a specified host and port.

In the code block above, you configured an Express application and registered the json() middleware, which parses incoming requests with JSON payloads and a matching Content-Type header.

If you try to access the application at this stage by running node index.js and navigating to http://localhost:3000 on a web browser, you'll be greeted by an error. There's no need to worry about this, however, as it just indicates that there are no routes or logic configured in your application yet. In the next section, we'll add some logic and set up the application's documentation with express-openapi, an OpenAPI framework for Express.

Integrating OpenAPI with express-openapi

For developing APIs, it helps to think of the API as a collection of resources, with each resource represented by a simple object that can be—from the moment of its creation—viewed, modified, or destroyed.

For simplicity, you can use this create, read, update, and delete (CRUD) pattern to help plan or design your API quickly. You can set up an OpenAPI-compliant API in a few steps using the express-openapi package. For this one we will assume that our project has only one resource, called User.

express-openapi is an un-opinionated OpenAPI framework for Express, which supports OpenAPI versions 2.x and 3.0 at the time of writing. Configuration can be done in JavaScript or from a YAML string/file. In this project, you'll be using a JavaScript object.

express-openapi allows you to keep the OpenAPI definition in sync with the code. Basically, you will provide an OpenAPI definition file with empty paths and they will be populated from your code. Doing this ensures the OpenAPI file will be exactly reflecting how the code behaves, updated as the code is. It also allows you if you go play around with the tool to validate your schemas, automatically provide res.validateResponse tailored to a particular route, helps with your API security management, and so much more I can’t list them all now. The whole purpose of this framework is to stay as close as possible to express while leveraging the power of OpenAPI.

To get started, run this command in your terminal to install the package:

npm install express-openapi

Open the index.js file in your editor and add the following import near the top of the file:

import { initialize } from 'express-openapi';

The initialize import is a function that accepts a configuration object and sets up an OpenAPI-compliant contract that can be viewed or generated for your API. The required configuration parameters are as follows:

a reference to an Express application
an operations object containing exposed HTTP methods and handler functions
a paths string that points to a directory where route files can be found
an apiDoc object describing the API's base definition, including schemas of objects used in your documentation

Note that either operations or paths will be required at any time. This means that if operations is present, then paths isn't required and vice versa.

Now make the following changes to the index.js file to see what this config looks like in action.

As first argument, you need to pass a reference to your Express app, then optionally specify a path to the docsPath keyword if you want the API contract file to be served by your server, in development mode this can be useful (as you will see later when using the Bump.sh CLI), however in production mode you might want to remove this and replace it with the exposeApiDocs: false option. Something like:

initialize({
  app,
  docsPath: "/api-definition",
  exposeApiDocs: (ENV["NODE_ENV"] !== "production"),
});

Next, configure the apiDoc object by specifying the path of a file containing the base of your API definition. In this tutorial, you'll be using OpenAPI 3.1. Add the apiDoc file path to the initialize config object:

initialize({
  // other objects here..
  apiDoc: "./doc/api-definition-base.yml",
})

And create the file ./doc/api-definition-base.yml with the following content:

openapi: "3.1.0"
info:
  title: "A getting started API"
  version: "1.0.0"
servers:
  - url: "/"
paths: {}
components:
  schemas:
    User:
      required: ["name"]
      type: "object"
      properties:
        id:
          type: "string"
          description: "The user's unique identifier"
        name:
          type: "string"
          description: "The user's preferred name"
        email:
          type: "string"
          description: "Email address"

Note that the API definition paths property is an empty object. This is because express-openapi will generate its members based on the value of the paths property given in the initialize function dynamically, which you'll add next.

To do this, we will import javascript files by adding the folder path or our API endpoints logic to the initialize function call:

initialize({
  // ...
  // rest of code omitted for clarity
  paths: "./paths",
})

Finally, you'll need to add a route with some operations to complete the express-openapi initialization. The express-openapi package uses filesystem-based routing. Let's look at the following routes we want to define:

GET /users
PUT /users/:id

They would need the following files to be created (assuming ./ is the starting directory):

./paths/users.js
./paths/users/{id}.js

While we'll be using more routes, these two files will be enough for what our project needs, so go ahead and create them:

mkdir -p paths/users
cd paths
touch users.js
cd users
touch {id}.js

We'll add some logic to our API application inside these files. Each file will contain a function as its default export, and this function will act as the corresponding path handler. For example, requests sent to /users will be handled by the function exported in ./paths/users.js, and requests sent to /users/{uniqueId} will be handled by the function exported in ./paths/users/{id}.js.

First, open the users.js file and add the following code:


export default function () {
  let operations = {
    GET,
    POST,
  };

  function GET(req, res, next) {}

  function POST(req, res, next) {}

  GET.apiDoc = {};
  POST.apiDoc = {};

  return operations;
}

Next, add the following code to the users/{id}.js file:

export default function () {
  let operations = {
    GET,
    PUT,
    DELETE,
  };

  function GET(req, res, next) {}

  function PUT(req, res, next) {}

  function DELETE(req, res, next) {}

  GET.apiDoc = {};

  PUT.apiDoc = {};

  DELETE.apiDoc = {};

  return operations;
}

Let's quickly break down what's happening in these files:

You have a function as the default export, and this function returns an object representing valid operations (HTTP methods) for the route.
As mentioned earlier, the file names correspond to the route that will be matched when your API is queried.
For each operation defined in the operations object, you need a corresponding handler function, and the function name must match the HTTP verb (PUT, GET, etc).
Finally, the documentation for each handler function can be described by adding an apiDoc property to the handler functions.

What's missing now are: your API documentation and the actual API logic. We'll add those in the next few steps.

First let's add your API endpoints documentation. We will update the apiDoc property for the GET and POST handler functions in the users.js file:

// ./paths/users.js
// rest of code hidden for clarity

GET.apiDoc = {
    summary: "Returns list of users",
    operationId: "getUsers",
    responses: {
      200: {
        description: "List of users",
        content: {
          "application/json": {
            schema: {
              type: "array",
              items: {
                $ref: "#/components/schemas/User",
              },
            },
          },
        },
      },
    },
  };
  POST.apiDoc = {
    summary: "Creates a new user",
    operationId: "createUser",
    requestBody: {
      content: {
        "application/json": {
          schema: {
            $ref: "#/components/schemas/User",
          },
        },
      },
    },
    responses: {
      201: {
        description: "Newly created user",
        content: {
          "application/json": {
            schema: {
              $ref: "#/components/schemas/User",
            },
          },
        },
      },
    },
  };

// rest of code hidden for clarity

We'll also add the documentation for the GET, PUT, and DELETE handler functions in the users/{id}.js file:

// ./paths/users/{id}.js
// rest of code hidden for clarity

GET.apiDoc = {
    summary: "Returns a single user",
    operationId: "getOneUser",
    parameters: [
      {
        name: "id",
        in: "path",
        required: true,
        schema: {
          type: "string",
        },
      },
    ],
    responses: {
      200: {
        description: "User data",
        content: {
          "application/json": {
            schema: {
              $ref: "#/components/schemas/User",
            },
          },
        },
      },
    },
  };

  PUT.apiDoc = {
    summary: "Updates an existing user",
    operationId: "updateUser",
    parameters: [
      {
        name: "id",
        in: "path",
        schema: {
          type: "string",
        },
        required: true,
      },
    ],
    requestBody: {
      content: {
        "application/json": {
          schema: {
            $ref: "#/components/schemas/User",
          },
        },
      },
    },
    responses: {
      200: {
        description: "Updated user",
        content: {
          "application/json": {
            schema: {
              $ref: "#/components/schemas/User",
            },
          },
        },
      },
    },
  };

  DELETE.apiDoc = {
    summary: "Deletes an existing user",
    operationId: "deleteUser",
    parameters: [
      {
        name: "id",
        in: "path",
        required: true,
        schema: {
          type: "string",
        },
      },
    ],
    responses: {
      204: {
        description: "No content",
        content: {},
      },
    },
  };

The apiDoc property of a function handler defines the OpenAPI documentation for that endpoint while the summary and operationId fields provide a brief description and a unique identifier, respectively. Route parameters and the required format for the request body data can be configured with the parameters and requestBody fields, respectively. Finally, the responses field provides information about the possible responses—and their status codes—for an endpoint.

Next, update the function handlers to include CRUD logic:

// ./paths/users.js

// rest of code hidden for clarity

function GET(req, res, next) {
  res.status(200).json(mockDatabaseInstance.getAll());
}

function POST(req, res, next) {
  const data = req.body;
  mockDatabaseInstance.addUser(data);
  res.status(201).json(mockDatabaseInstance.getAll());
}

The GET and POST function handlers here respond to GET and POST requests made to /users, respectively. The GET function retrieves all user data from a database, the mockDatabaseInstance—which we'll get to later—and returns it in JSON format with a status code of 200. The POST function adds a new user to the database from data provided via the request's body and returns the updated user list with a status code of 201.

We'll also need to update the function handlers in the /users/{id}.js file. Open the file and update the GET, PUT, and DELETE functions to include the following code:

// ./paths/users/{id}.js
// rest of code hidden for clarity

function GET(req, res, next) {
  const user = mockDatabaseInstance.getOne(req.params.id);
  res.status(200).json(user);
}

function PUT(req, res, next) {
  const data = req.body;
  const updatedUser = mockDatabaseInstance.updateUser(req.params.id, data);
  res.status(200).json(updatedUser);
}

function DELETE(req, res, next) {
  mockDatabaseInstance.deleteUser(req.params.id);
  res.status(204).send();
}

As mentioned earlier, requests made to /users/someUniqueId will be routed to this file and handled according to their HTTP verbs. The GET function here retrieves a single user from the database, matching the ID provided in the request's path. The PUT function updates a single user, also matching the provided ID, and returns the updated user as JSON with a status code of 200. The DELETE function removes a user from the database using the ID provided in the request. No data is returned from the DELETE function, so the status code is 204.

The mockDatabaseInstance object referenced in the function handlers code is a simple object with methods for updating and reading from an in-memory data store (an array of objects). We can add this to our project by creating a file named database.js in the project root:

touch database.js

And adding the following code to the file:

function mockDatabase() {
  const dataStore = [];

  function userExists(id) {
    return dataStore.findIndex((value) => value.id === id) !== -1;
  }

  function addUser(data) {
    if (userExists(data.id)) {
      // user already exists, let's throw an error
      throw new Error("User already exists.");
    }
    dataStore.push(data);
  }

  function updateUser(id, data) {
    if (!userExists(id)) {
      // user does not exist, let's throw an error
      throw new Error(`No user with ID ${id} was found`);
    }
    const index = dataStore.findIndex((value) => value.id === id);
    const updatedUser = {
      ...dataStore[index],
      ...data,
      id,
    };
    dataStore.splice(index, 1, updatedUser);
    return updatedUser;
  }

  function deleteUser(id) {
    if (!userExists(id)) {
      // user does not exist, let's throw an error
      throw new Error(`No user with ID ${id} was found`);
    }
    dataStore.splice(
      dataStore.findIndex((value) => value.id === id),
      1
    );
  }

  function getAll() {
    return dataStore;
  }

  function getOne(id) {
    if (!userExists(id)) {
      // user does not exist, let's throw an error
      throw new Error(`No user with ID ${id} was found`);
    }
    return dataStore.find((value) => value.id === id);
  }

  return {
    addUser,
    updateUser,
    deleteUser,
    getAll,
    getOne,
  };
}

const mockDatabaseInstance = mockDatabase();

export default mockDatabaseInstance;

The code above defines a function named mockDatabase that returns an object with multiple functions to perform CRUD operations on an in-memory data store, the dataStore array. The functions addUser, updateUser, and deleteUser respectively perform operations to add, update, or delete users from the data store. The getOne and getAll functions retrieve one or multiple users from the data store, while userExists is a utility function for checking if a user with a matching ID exists in the data store.

We instantiate and store the mockDatabase in the mockDatabaseInstance variable, and we export and use this in our function handlers. Let's update the rest of our code to include the mockDatabaseInstance import.

Open the files in your paths directory, and add the following line at the top of each file:

import mockDatabaseInstance from "../database.js";

Note that for the paths/users/{id}.js file, you need to add two dots and a slash (../) as it's nested one level deep:

import mockDatabaseInstance from "../../database.js";

With that, your API and its contract have been set up. When you test your application in the next section, you'll see that errors will be thrown for invalid requests or payloads that don't conform to the documentation you've described. This is where the express-openapi library shines as you didn't need to define any validation code but the provided documentation schemas and constraints will do all the job for you.

While you've learned to create an Express application with express-openapi in this section, it's been light on information about the OpenAPI specification and the express-openapi package. You can start with the OpenAPI guide if you'd like to learn more about the OpenAPI specification and the express-openapi documentation for more information on how to use the package.

Running and Testing the Application

It's time to run and test the application. Simply run node index.js and navigate to http://localhost:3000/api-definition in a browser to see your API definition.

You can also test the API by visiting http://localhost:3000/users to list the users in your database.

In a production environment, you will probably want to deploy the updated API definition each time you make a change in your code without having to expose the API definition on your express server.

To do so, copy the following script into a new file named contract.js:

import OpenAPIFramework from "openapi-framework";

// Use OpenAPIFramework similarly than in the express-openapi library
// to generate the OpenAPI definition file of our API
const framework = new OpenAPIFramework.default({
  featureType: 'middleware',
  name: "express-openapi",
  apiDoc: './doc/api-definition-base.yml',
  paths: "./paths"
});
await framework.initialize({});

// Output OpenAPI definition
console.log(JSON.stringify(framework.apiDoc))

This is a simple script which uses the express-openapi package to generate the API definition file without the need to run an Express server.

So if you run the following command:

node contract.js > doc/api-definition.json

You will be able to snapshot the current OpenAPI definition file inside the doc/api-definition.json file.

Using Bump.sh for Documenting Your Express APIs

Using OpenAPI (and the express-openapi package) enables you to use API contracts that make collaboration easy among developers when building and integrating with APIs. However, manually generating and maintaining these contracts can be tough, as you just saw. Bump.sh can improve this collaboration by helping documenting your API based on the contract.

As an API documentation management solution, Bump.sh helps publish API contracts into developer portals, track changes, and alert teams when breaking changes are introduced. It essentially eases the workload of manually updating your API's documentation, communicating changes made to your API's consumers, and keeping track of all your product documentation.

Bump.sh provides a command line interface (CLI) tool that lets you easily preview your API documentation while it's in development (with support for live reloading), deploy versions of your documentation automatically from your CI build step, compare changes made between versions of your API, as well as notify consumers of changes made to your APIs.

Configure Bump.sh for Express Applications

To configure Bump.sh for your Express app, you need to add the Bump.sh CLI to your existing Express project:

npm install bump-cli

As mentioned, bump-cli can be used to preview, compare versions, or deploy new versions of your API documentation.

Sign up or login in your Bump.sh account. You can begin by navigating to your dashboard and clicking Create Documentation.

Next, add your documentation's name and, optionally, specify its access level (public or private).

Next, you'll be asked to upload a specification file. Choose the Use Bump.sh CLI option, which will immediately take you to the newly created documentation's deployment configuration page. Here, you'll find the token that's required to deploy your documentation using the CLI. It's the string labeled Access token, as shown below.

Copy this token and replace YOUR_TOKEN with it when running the command to deploy your project:

npx bump deploy http://localhost:3000/api-definition --doc YOUR_DOCUMENTATION_SLUG --token YOUR_TOKEN

Running the command above will trigger a deployment that you can view by clicking View Documentation from your documentation's General Settings page.

Your deployed documentation should open in a new tab, and it should look like this:

Automate API documentation update with Bump.sh

In order to automatically deploy a new version of your documentation every time you push code changes to a branch, we will add the Bump.sh Github Action to your repository.

To deploy a new version on each push, create a file named bump-deploy.yml in the .github/workflows folder of your project, then paste the following code into the file:

name: Deploy documentation

on:
  push:
    branches:
      - main

jobs:
  deploy-doc:
    name: Deploy API doc on Bump.sh
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install NodeJS
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - name: Install node dependencies
        run: npm ci
      - name: Generate OpenAPI contract
        run: node contract.js > doc/api-definition.json
      - name: Deploy API documentation
        uses: bump-sh/github-action@v1
        with:
          doc: <BUMP_DOC_ID>
          token: ${{secrets.BUMP_TOKEN}}
          file: doc/api-definition.json

This workflow runs every time git push is run on the main branch. It will generate the API definition thanks to the contract.js script, then deploy the API definition file to Bump.sh thanks to the Bump.sh Github Action.

Just make sure you provide your Bump.sh documentation slug (replace the <BUMP_DOC_ID> value) and an encrypted secret containing the Bump.sh access token used earlier in a BUMP_TOKEN secret variable on your repository.

The resulting action should run on each push to the main branch:

Your API consumers can then subscribe to changes made to your API by clicking on API Changelog from your API documentation page. Either by completing the form or adding the RSS feed link to apps that can display RSS feeds.

Conclusion

By following this tutorial, you created an Express application and documented the API according to the OpenAPI specification with the express-openapi npm package. You also learnt how to deploy a live version of your API documentation using Bump.sh.

Documenting your APIs correctly is key to your API quality, usability, maintainability and helps your API consumers quickly get up to speed with using your product, reducing the number of support tickets and issues related to consuming your API.

Bump.sh helps with documenting your APIs but goes one step further by giving you tools like an automatic API changelog with notifications and diffs and a hub to manage all your API documentation in one place.

Author: Jerry Ejonavi

A Developer's Guide to API-First Design

Bump.sh — Wed, 14 Jun 2023 12:30:00 +0000

API-first design is a software development approach built around the idea that the application programming interfaces (APIs) should be the primary focus of the development process, with other system components, such as the user interface (UI) being developed later.

API-first design is becoming increasingly important as more and more organizations are turning to microservices and other architectural patterns to improve their ability to scale, innovate, and adapt to changing business needs. This approach enables the development of flexible and modular systems that can be easily integrated with diverse systems and services.

In this article, you'll learn about the principles of API-first design and how it can benefit your organization. You'll understand how API-first design works and learn about the different stages of the API design process. By the end of this article, you'll have a comprehensive understanding of the benefits of API-first design, and how Bump.sh can serve as the single source of truth for all your APIs.

Why Is API-first Design Important?

As mentioned, API-first design is a specific methodology for building software systems, where the API is designed and developed before any other system components. APIs are emphasized as a core part of the software development process rather than as an afterthought. In short, the API is considered the backbone of the software, and the rest of the system is built around it.

// Detect dark theme var iframe = document.getElementById('tweet-1592921944818491394-869'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1592921944818491394&theme=dark" }

API-first design is commonly applied in API-centric products. For example, companies like Stripe or Twilio offer their APIs as a core offering to customers, so they have to design them to be intuitive and user-friendly.

Companies using or moving to a microservice architecture will also often adopt an API-first design approach. Because APIs are so important in microservices, developing standards and a well-thought-out workflow through API-first design is very important.

When done well, API-first design offers a number of benefits:

Faster Development Times

By designing the API first, development teams can more easily work in parallel on different parts of an application. Having a well-documented API means that teams can stub out specific endpoints to test and build their own systems without having to have a running instance of every API on their machine.

Similarly, this improves coordination between frontend and backend teams. Frontend developers can build based on the assumption that the backend will adhere to the established documentation, allowing backend developers to work in parallel with them.

Finally, API-first design makes it easier to reuse endpoints and logic throughout the system. For example, if you’re building an e-commerce application, several parts of the application may need to estimate shipping costs (e.g., pricing page, checkout workflow, returns workflow, invoice generation, etc.). If there’s a single, documented endpoint available, you can ensure that each time it is called, the results will be the same.

Improved Developer Experience

It’s often easy to tell when a system wasn’t built with the API in mind because it uses clunky or non-standard endpoints. For example, I recently ran across an API that used the following endpoint to edit a user object:

POST http://api.example.com/v1/user/edit

While this approach technically works, it’s not common. Typically, in a REST API, modification of an object would use a PUT or PATCH request and include the object’s ID in the URL. So, consumers of this API must now very carefully read through all the documentation to be sure they use your API properly.

Whether API consumers are internal or external, systems designed with the API in mind first will almost always provide a better experience to developers. They’re more likely to use established standards which make them much easier and less frustrating to use.

Better Collaboration and Communication

Ultimately, all the advantages of API-first design come down to making communication and collaboration better.

When your API is clearly defined and agreed upon up-front, multiple teams can work in parallel, engineers can move from working with one API to another seamlessly, and errors in the implementation or consumption of APIs are more clear.

When is API-First the Wrong Approach?

Just because there are advantages to API-first design doesn’t mean it’s a panacea. For example, if you’re building a traditional server-rendered application without plans to offer an API, adding extra layers is a waste of time. API-first design can also hamper nascent projects that aren’t sure exactly how the data model will look when they’re finished.

Overengineering is a common problem in software development, and API-first design approaches are no different.

The API-First Design and Development Process

Now that you've seen some of the advantages an API-first process provides, let's get into the practical aspects—what does API-first design look like?

As the name implies, API-first design dictates that you plan your API as part of the application development process, but like all software, your API needs to be open to change as the system around it changes.

Typically, a new API will undergo the following stages:

Define

This is the initial stage of the API lifecycle, where you’ll define and establish the API's overall goals, requirements, and constraints. This stage is critical for setting the scope of the project and ensuring that the final API will meet the needs of its intended users and stakeholders.

At this point, you should consider the technical and service-level requirements, the data format users will prefer (JSON, XML, etc.), the data structure, and the downstream systems that rely on your API. You should also consider the audience for this API. Will it be publicly available? For private or internal use only? Or limited to verified partners?

Finally, you should define any key roles or processes your team will use while building and maintaining the API. You’ll need to decide on the tools you’re going to use to design and document the API as well as a plan for change management.

Design

Next, you will outline the API's design and structure. Based on the performance, scalability, security, and other requirements outlined in the Define stage, you will need to make decisions like whether to use REST, GraphQL, or gRPC, how to authenticate and authorize consumers, and how to report and track errors.

During this stage, you can create API contracts that provide clear guidelines for the API's behavior. Assuming an HTTP API, developers will often use a standard specification like OpenAPI or AsyncAPI to define the API’s operations (verb and URL) and response format. Having contracts like this allows developers to properly implement the API, and it lets consumers mock the API so they can build downstream applications.

Develop and Document

In the next stage, you will implement the API, and create the necessary documentation.

Traditionally, documentation has been a manual process, but API tooling has come a long way, and now you can use tools like Bump.sh to automatically generate your API documentation from your contract defined during the design phase. This allows your developers to focus on implementing the API and building internal business logic without having to worry if they’re keeping their documentation up to date.

As in building any web application, you’ll need to make decisions about the internal architecture of the API (framework, language, database, etc.), the ancillary services needed (message queues, notifications, etc.), and deployment options. If you’re in an established organization, many of these decisions might be mandated externally, but in greenfield projects, there’s often a lot of leeway.

Test

Before deploying an API, it's important to thoroughly test it to ensure that it behaves as expected, meets the outlined spec, and will continue to behave as expected as the API changes. Typically, this includes unit testing, integration testing, and load testing. While automated testing should comprise the bulk of your API tests you’ll likely want to do some manual QA as well to catch any unexpected behaviors before you launch.

After launch, testing is equally important, so focus on building repeatable testing practices: run them as part of your CI pipeline, keep an eye on code coverage metrics, and don’t let test debt pile up. As you might imagine, these tests will be invaluable once your API starts changing and growing.

Secure

While security should have been considered at the design stage, this point is important enough to check again after implementation. You want to prevent any unauthorized use or abuse of your API to ensure that sensitive data is protected. Encryption, access controls, user authentication, and other security measures should all be tested and verified before deployment. All the security checks that can be repeated should also be included in your CI processes so they are conducted continuously.

Most high-stakes API projects will have penetration tests conducted by internal or external auditors. If you’re new to API security, familiarize yourself with the OWASP API Security Top 10 and make sure you’re covered.

Deploy

After testing and securing the API, you can deploy it for use by its intended audience. Obviously, the specifics of this step vary greatly depending on your tech and infrastructure stack, but most companies use multiple environments to ensure their API can be deployed and that changes don’t cause unintended consequences when they’re released.

Observe

Observability has come a long way in the past few years, and modern tools allow you to easily track your API's usage, performance, access logs, and errors. Instrumentation should let you catch issues and help you understand how consumers are using the API.

Evolve

It is worth noting that this API development lifecycle isn’t a one-time process. Like most software projects, you’ll come back to implement changes frequently, so you’ll need to have a plan for implementing, testing, and announcing those changes.

Tools like Bump.sh can help with this as it can track structural changes to your API to automatically update a changelog and trigger a webhook to notify other services.

Finally, this lifecycle isn’t necessarily linear: you may need to move backward before you can move forwards. For example, during the development stage, teams may find that certain requirements must be re-evaluated or redesigned. Or, during the testing stage, they may discover issues that require changes to the API's design or implementation. In such cases, teams may need to go back to a previous stage of the API lifecycle to address these issues before moving forward.

Developer API Tools

I’ve hinted at tooling a couple of times in this piece, but because it’s such an important part of building a great API, I’ll dig deeper here. There are a few categories of tools that are important when designing and building APIs, including:

Documentation tools range from presentation-only tools to automatic doc generation tools. In any case, you’ll definitely need some way to document your API and manage changes.
Mocking tools allow you to stub all or part of your API so consumers can work without a deployed version.
Testing tools come in many different shapes and sizes but most will allow you to automatically run and call endpoints with various parameters to ensure the results match your expectations.
An API browser can be helpful for browsing and troubleshooting endpoints or testing specific requests.

Finding the right mix of tools often comes down to personal preference, cost, and ease of use or implementation. Ultimately, what works for one company might not work for another, so it’s important to evaluate all the options in your unique context.

Conclusion

API-first design is a powerful way of building software that prioritizes APIs and their consumers. Development teams can create better products and more efficient workflows by designing APIs first and then building the rest of the application around them.

Additionally, by thinking about the API from the beginning of the development process, teams can better anticipate the needs of third-party developers and create a more user-friendly experience for them. Overall, API-first design is a key strategy for creating high-quality, effective APIs that are well-suited to the needs of modern software development.

Getting your API-first design efforts off the ground can be made easier with Bump.sh. Bump.sh is the simplest way to automatically create API documentation portals for internal, partners, and public APIs. Feel free to look at our solution, and please reach out to us if you have any feedback, comments, or suggestions you'd like to share. We're always listening.

Author: Alex Doukas

API Contracts - an Extended Introduction

Bump.sh — Mon, 12 Jun 2023 15:08:33 +0000

An API contract is a document that showcases how an API behaves and how it should be used.
This article is all about API contracts: how they can help your business, the best practices to follow, as well as some practical examples.

Why Are API Contracts Important?

The purpose of an API contract is to ensure developers using the API can interact with it in a consistent and predictable manner.

A consistent API contract also helps standardize integration with other systems, reducing misunderstandings and errors.

It's a useful tool for promoting a shared understanding of your API, easing in changes, and assuring the users of your APIs stability and reliability.

Having a defined API contract helps streamline processes for both internal and external API users. When multiple external systems or teams are involved, a contract can help avoid misunderstandings and reduce the risk of API usage errors.

It’s also important in API-first design as downstream teams will often start building mocks of your API before the first version is actually live. Your API development team’s process is also improved with a contract in place, as there's a clear set of guidelines for how the API should behave.

API contracts can contribute to the security and dependability of the systems that use them. By specifying rules around how different systems should interact, API contracts can help prevent misuse of data and ensure that systems can recover gracefully from errors or failures. Good API contracts will also include details about authorization, request limits, and usage restrictions, which helps users avoid accidentally losing access.

Finally, almost any API that uses a strict contracting process will have better documentation than one that doesn’t. Often, API contracts are turned directly into documentation, making the lives of development teams much easier.

What Are API Contracts ?

API contracts can take many forms, such as a document describing the interface, a formal specification written in a particular language, or a set of code examples illustrating how the API should be used; it can also be written in a combination of formats.

API Contracts often follow a preexisting specification like OpenAPI, gRPC, GraphQL, AsyncAPI, or Blueprint.

Using an established standard helps new developers working with your contract learn it faster and it helps your development team save time on creating and maintaining the contract. Most standard come with a set of tools and a publicly available community which gives them the advantage of almost always being better than coming up with your own API contract from scratch.
These contracts typically set out information such as the API's expected behavior, data formats, authorization and authentication processes, error handling, and limitations. Seeing how the contract changes over time can also help users understand changes to your API as new versions are released.

It may include details about the specific endpoints (i.e., URLs) that can be called, the parameters that can be passed to those endpoints, and the responses that will be returned. Some API contracts may also include information about authentication and authorization, error handling, and other details that are key to proper integration.

What Should You Consider When Designing an API Contract?

Here are some basic concepts to keep in mind while designing your API contract:

Keep it simple, easy to understand, and consistent: In most cases, you should use a predefined specification (as mentioned above) to help users learn and integrate your API into their applications more quickly while reducing the scope for misunderstandings or errors. A uniform vocabulary and style across the contract can also help developers identify what they need and quickly understand how to use the API.
Document all parts of the API: This API contract will be a very good place for everyone interacting with your API to have a complete overview of it. The more it is exhaustive, the more they will be able to fully view and understand the structure of your API. Including elements such as inputs, outputs, error codes, etc. is enormously helpful in the implementation process. Examples are also beneficial as they offer a clear understanding of how the API works and how to incorporate it into applications.
Thoroughly test the API against the contract: You should test the implementation of your API against the stated contract before release, and provide means of reporting changes - especially breaking ones - or inconsistencies as the API evolves. This means your contract should be in a format allowing your QA process to read and validate against it. Ideally, the testing process should be automated so your API can be validated during the continuous integration process each time changes are made.

API Contracts: Best Practices

Defining the Expected Behavior of the API

At a minimum, your API contract should showcase the expected behavior of your API and its endpoints as well as explore details about how an application will call the API. Here's an excerpt of an API contract showcasing the API behavior and the data you can get from it:


GET /weather

Input parameters:
- location (string): The location for which to retrieve weather information (e.g. "New York, NY")
- version (string): The version of the API to use (e.g. "v1", "v2")

Output:
- temperature (float): The current temperature in degrees Fahrenheit
- condition (string): A description of the current weather conditions (e.g. "sunny", "cloudy", "rainy")

Example usage:

GET /weather?location=New%20York,%20NY&version=v2

Output:
{
  "temperature": 72.5,
  "condition": "sunny"
}

[Representation of the behavior of the API]

Your contract should always provide details on how your users can utilize your API. This excerpt, for example, specifies that the API can be accessed using a GET request to the /weather endpoint and that it takes an input parameter, location, which is a string representing the location for which to retrieve weather information. The second input parameter, version, is also a string and represents the version of the API the user would like to interact with.

It also makes clear that the API returns a JSON object with two fields: temperature, which is a float representing the current temperature in degrees Fahrenheit, and condition, which is a string describing the current weather conditions.

Specifying the Contract and API Version

It is common, on an API lifecycle, to see changes to the API behavior itself. As an API grows, changes will be made to the current version of the API. The contract is a good place to communicate to your users and API consumers about the changes in your API and how to keep using your API service after the change applies.

If you need to make a breaking change or your API grows and changes so much that you have the need to release a new version of it, you will need to create a new contract. Each version of your API should possess its own. And ideally each version of the API has their own documentation.

Your contract should note which API version it services.
It should also display the API contract version, which can be different from your API version. For instance, in the OpenAPI spec, an info.version field is used to explicitly state the version or revision of the API contract in use.

info:
  description: "A simple API example."
  title: "Example"
  version: "1.2"

[An example of how to specify the version according to the Open API spec]

As your API contract and API versions change, you should ensure these are noted in your changelog or release notes. This helps users know when a breaking release is made and what they need to do to keep their implementation working.

Document Data Formats, Limitations, and Restrictions

Your API contract should accurately document the peculiarities and formats of data that a user might receive from API calls. Data normalization is notoriously difficult, so you want to help your API’s users as much as possible by giving them clear descriptions of return types and input expectations.

It should also set out the limitations that the user should be aware of as they implement the API — for example, rate limits, availability schedules, and requirements for access to certain data. If these constraints are not clear it can be frustrating for users who suddenly hit unexpected limits.

API Contract at the Age of Automation

Your API contract does not only allow you all the things listed above, it’s also a good piece to add in your automations.

A common practice is to have your unit tests results tested against the API contract. You can make your CI process fail if the behavior of the API is not matching the expectations of the contract, and you can also analyze changes (including breaking changes) directly from the CI as well.

What’s Next for your API Contract ?

Once you’ve defined your contract and implemented your API, you can use a tool to create the user-facing documentation. In addition to documentation generation based on API contract documents, Bump.sh also integrates with your CI pipeline to ensure that changes to the API are noted in the documentation upon each release.

If you’re interested in learning more about API design or development, be sure to check out the Bump.sh blog, or sign up for free to see how Bump.sh can help you generate user documentation more easily.

Creating Better API Architecture Diagrams

Bump.sh — Mon, 12 Jun 2023 14:59:34 +0000

Architecture diagrams are essential in the API development process. They provide a map of how different systems interact to help software teams manage and maintain them, and they provide insight into the architect’s vision for the entire system. Along with other elements like interactive API portals, API architecture diagrams also help enrich your API’s documentation.

This guide will share more about the various types of API architecture diagrams and some tips for creating them. You will see several examples of these diagrams and learn about the utility of UML for modeling them. Finally, you’ll get some best practices for creating architecture diagrams as a supplement to your API documentation.

What are API Architecture Diagrams and Do You Need Them?

API architecture diagrams are visual representations of the structure and interactions of the components of an API. They can help developers and architects plan the interface structure, users understand the intended use of the API, and they can also help QA engineers better test and debug the API.

Typically, an API architecture diagram will identify the various API components, their relationships with each other, and the data flow between them, but as you’ll see in this piece, there are many types of API diagrams worth looking at.

// Detect dark theme var iframe = document.getElementById('tweet-1356308080389193728-149'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1356308080389193728&theme=dark" }

Unfortunately, creating a good API architecture diagram takes time. As the author of the Tweet above points out, this particular diagram took 10 hours of work to complete. So, creating diagrams like this can be helpful, but your engineering and documentation teams will need to make time to get them right.

Types of API Architecture Diagrams

Depending on the API you’re documenting, the communication protocols you’re using, the complexity of the system, and the goals of the architecture diagram, you may diagram the API differently. In this post, I’ll primarily focus on diagramming REST APIs, but the types of API diagrams you can create are basically endless.

That said, here are a few interesting common types of API architecture diagrams:

Sequence Diagrams

One way to use an API diagram is to illustrate a specific workflow that consumers need to know about. A sequence diagram often includes the HTTP verb (GET, POST, PUT, or DELETE) and resource name for each API call in the diagram. They can also be useful for noting any custom calls (like bulk endpoints) that your API offers.

The API diagram above uses the order of arrows to indicate the order in which the calls should be made. Complex workflows like authentication and authorization often require API calls to be made in a very specific order, so API architecture diagrams can help clarify this.

Example of a REST API sequence diagram with swimlanes.

Service Architecture Diagrams

Another way to use API architecture diagrams is to show how multiple services are connected and integrated with one another.

The diagram above shows how an online store’s architecture diagram might look, including the resources, endpoints, and attributes of each resource.

Service Architecture Diagrams help new users get a “lay of the land” when it comes to your API, meaning they can quickly see how all the resources and data models are related. This can help them plan out their application, especially if they’ll rely on several endpoints or services within your ecosystem.

Internal API Architecture Diagrams

Finally, your diagram might be focused on illustrating the internal architecture of your system rather than the external.

These diagrams are useful for other engineers at your company to see how the system is designed so they can better understand errors and debug errors faster. They help new engineers onboard faster, and can serve as a reference point when designing new systems at the company. Finally, they help with internal processes like security audits as knowing all the layers a request goes through before accessing your data can help identify vulnerabilities.

Tools for Creating API Architecture Diagrams

Now that we have covered some types of API diagrams you might use, the next step is to figure out how to actually create the model for your API architecture diagram. There are many different tools available depending on your preference, team’s experience, and the purpose of your diagrams, but let’s take a look at three.

Unified Modeling Language (UML)

Engineers have a range of visual language models they can use to create graphical diagrams of software systems, but one of the most common standards for diagramming is Unified Modeling Language (UML). Many developers choose UML because of its:

Widespread use - Using a standard like UML ensures that multiple members of your team can pick it up and make modifications to the diagram in the future.
Flexibility - Although the UML has a vast library of symbols and concepts designed explicitly for creating software architecture diagrams, you can also customize its elements to fit whatever technologies your project uses or visual representations you want to create. UML is not limited to object-oriented software modeling, but is also commonly used to explain business processes.
Tooling - The popularity of the UML has led to the creation of a number of tools ranging from online tools for creating UML diagrams, to tools for generating code from diagrams. This ever-growing ecosystem of UML tools makes it more convenient than other languages of its kind.

The downside to UML is that you have to learn its way of doing things, so there’s a bit of a learning curve to it.

Mermaid

UML is just one format for diagram design specifications. Another option is to use a code to diagram tool like Mermaid. Mermaid transforms plain-text (Markdown inspired text definitions in this case) into full-fleshed visual diagrams. Their tool is open-source and written in JavaScript, making it easy to customize if you’re so inclined. Advantages include:

Ease of Use - Markdown is a well-established language for developer documentation, and their live editor includes examples to help you get started.
Customizability - In addition to being open-source at its core, Mermaid allows you to build themes on top of the core product or use the API to generate diagrams programmatically.
Integrations - You can install Mermaid on your own server or embed it directly into your documentation or developer portal, making it one of the most flexible options out there.

Downsides to Mermaid could be:

The default chart and diagram types are limited. As mentioned, you can customize it as much as you want to create new types of diagrams, but that takes a fair bit of work and programming knowledge.
Mermaid uses its own syntax. Even though it’s based on Markdown as mentioned above, it does take a bit of practice before you’ll be completely used to the tool.

Lucidchart

Another approach to creating API architecture diagrams is using a tool like Lucidchart, which sort of combines the best of a structured language like UML with an open-ended drawing tool. This makes Lucid good for its:

Adaptability - With Lucid, you can create your own shared library of diagram elements (or use a standard like UML). These diagram elements can become your team’s visual language and help API diagrams across your entire company look similar.
Collaboration - As a purpose-built team diagramming tool, Lucid allows you to version and share documents with your team or the public.

The downside to Lucid is that it’s a little more complex to learn than a freeform drawing tool and it’s not free. After your 7-day trial, you’ll be paying—as of today—at least $9 per month for an individual account.

Finally, it’s worth noting that the three options above aren’t mutually exclusive, and there are many other tools you can use to create API architecture diagrams.

Best Practices for API Architecture Diagrams

Once you know what kind of API architecture diagram you need and how you’ll go about creating it, there are still a few design best practices to keep in mind. Even if your diagram is only intended for internal use, making it visually appealing can help people digest the information better and avoid confusion.

Use the Right Type of Diagram

I’ve already discussed a few types of API architecture diagrams above, but it’s worth noting that you need to consider the goals of your diagram before picking the type of diagram you should create. Remember, a good diagram takes time to design and maintain, so don’t do work you don’t need.

Think of Accessibility

Clarity is key when designing architecture diagrams. This is especially true for complex API diagrams, so it's a good idea to use contrasting colors and shapes for each type of component. You can play with colors, shapes, and background patterns for each component so they're easier to identify. Keep in mind that not all eyes work the same (for instance one in 12 men are colorblind), so high contrast between elements and text is very important. Tools like Sim Daltonism on osX can help ensure that your diagrams are readable for everyone.

Keep it Simple and Avoid Redundancy

Make sure your diagram is as straightforward to understand as possible. Avoid redundant elements or unnecessary complexity like intersecting lines. Also, promote readability by using swimlanes, leaving enough white space between diagram elements, and maintaining a uniform size of symbols and figures.

Avoid Jargon

To promote clarity and readability, it's good practice to use simple, easy-to-understand terms instead of technical jargon. In cases where this isn't possible, at least explain your terms. You can do this by including a key or legend along with your diagram.

Going Further

As mentioned previously, API diagrams are a great way to help a user understand your API. They're a great addition to the “Getting Started” section you’ll find in a lot of API documentation.

Bump.sh supports markdown descriptions and helps you share your API architecture diagrams via generated documentation based on an API contract.
To add an image to any markdown you just need the following syntax ![](https://rb.gy/i0zf0) where the link is a public URL to your image. More on that, brand new image sizing feature and best practices in the Images section of the documentation.
It you want to play even more with markdown, the x-topics property makes it easy to add relevant content sections to your documentation for a well-organized, reader-friendly structure.

Conclusion

In this article, you learned how API architecture diagrams can support your product and documentation efforts. You saw how diagrams can make systems that are easier to understand and maintain, and you learned about a few different types of API architecture diagrams that are available. Finally, you learned about a few tools and best practices for creating API architecture diagrams that are easier to read and maintain.

Diagrams are just one tool in a developer’s toolbox for providing clarity around their APIs. You’ll also need documentation (which often includes relevant diagrams), an API contract, and a change management system.

If you’re looking for more ways to provide clarity around your API, check out Bump.sh. Import API contracts into Bump.sh and automatically generate human-readable documentation, with change-tracking and notification capabilities.

Author: Damaso Sanoja

Using OpenAPI and AsyncAPI Tags to Better Organize API Endpoints

Bump.sh — Mon, 12 Jun 2023 14:49:20 +0000

OpenAPI Tags are a great way to organize the API endpoints in your API Contract.

When developing APIs, it's essential to document the API so that other developers, whether internal or external, can use the API effectively. OpenAPI and AsyncAPI are open source specifications useful when writing API contracts.
An API contract describes the API, including its endpoints, data structures, and security constraints. When writing these, you can use OpenAPI tags and AsyncAPI tags to help you categorize your contract so that it's more readable and easier to understand.

Let’s see how that works !

Tag Example

Typically, OpenAPI and AsyncAPI tags are used to group related endpoints in a meaningful way, such as by business function or logical objects. When using tags, you define an array of tags at the root of your document, like this:

tags:
  - name: Clients
    description: Create, update and retrieve client information.
    externalDocs:
      description: Read more
      url: http://docs.example.com/api/clients
  - name: Notifications
    description: Manage notifications for the current user

Once you've created these tags, you can use them to group related endpoints in your API using the tags property on the endpoint as follows:

paths:
  /clients:
    get:
      tags:
        - Clients
      summary: Retrieve all clients.
      description: Retrieves all clients the user has access to.
  /notifications/unread:
    get:
      tags:
        - Notifications
      summary: Retrieves all unread notifications.
      description: Retrieves all unread notifications for the current user.

You can also apply multiple tags to an endpoint, as shown in the code snippet below:

paths:
  /clients/{clientId}/notifications:
    get:
      tags:
        - Clients
        - Notifications
      summary: Retrieve all the notifications for a particular client.
      description: Retrieves all the notifications for a particular client that the user has access to.

Benefits of OpenAPI and AsyncAPI Tags

Tags are a powerful tool for improving the usability of your API contract. Below are some of the ways using tags can help keep your API contract organized.

Tags Can Describe Endpoint Groups

When specifying your tags in the root level of your API contract, you can give context to the tag using the description property.
Let’s take Bump.sh API documentation. Here is how the Diffs tag is created and described in Bump.sh API Contract:

tags:
  - name: Diffs
      description: Diff summary of changes in the API

The documentation will show the Diffs property like this:

See it live

Note that you can use markdown in the description field to better describe your tags.

Tags Can Link to Additional Documentation

While the description property is excellent for giving a little more information about a specific tag, you might need to provide additional documentation if the business logic or object represented by the tag is complex and requires further explanation. Let’s take our Diffs example from above. You can provide a link to an external web page where you offer a more detailed explanation using the externalDocs property.

In the code snippet below, the externalDocs property provides a link to a URL using the url property. A description for the URL can also be specified using the description property.

tags:
  - name: Diffs
    description: Diff summary of changes in the API
    externalDocs:
      description: More details about Diff
      url: https://docs.bump.sh/help/api-change-management/

When you generate API documentation for the API contract above, you'll see the link rendered like this:

Tags Can Order Endpoint Groups in Documentation

When specifying your OpenAPI or AsyncAPI tags in the root of your API contract, the order in which you list the tags will define the order in which they appear in the generated documentation. This ordering lets you sort the tags meaningfully.

tags:
  - name: Diffs
    description: Diff summary of changes in the API
  - name: Ping
    description: Monitoring status endpoints
  - name: Previews
    description: Preview for documentation file
  - name: Versions
    description: Deploy your API contracts
  - name: Validations
    description: Check & validate your API contracts
 - name: Hubs
    description: Interact with your Hubs

When you generate API documentation, you'll notice the documentation orders the endpoint groups in the same way:

See it live

Note that Bump.sh helps you order your endpoints and webhooks using a "Group by tag" operation. It is actually the default behaviour of Bump.sh when you have these tags defined and have not selected an other sorting option for your Bump.sh API documentation.

Now that you understand what tags are and their benefits, you'll see some best practices you should follow when using OpenAPI and AsyncAPI tags in API contracts.

OpenAPI Tags Best Practices

Tag Everything

When using tags, make sure you tag all your endpoints.
Notice how all diff-related endpoints are tagged with the Diffs tag in this snippet:

paths:
  /diffs:
    post:
    tags: [ Diffs ]
    summary: Create a diff
    [...]
  /diffs/{id}:
    get:
    tags: [ Diffs ]
    summary: Fetch detailed information from an existing diff
    [...]

You can see live how they are all available under the section Diffs. By clicking the name of the section in the left menu, the tagged endpoints will show up.

Untagged endpoints will not show up under any big section represented by a tag of your documentation generated by Bump.sh

To ensure your endpoints remain logically grouped and ordered, always tag every endpoint, even if it means creating a tag for a single endpoint.

Make Every Tag Unique

When defining the list of tags in the root of your API contract, make sure not to duplicate tag names. Since the tag's name property links an endpoint to a tag, duplicate names are likely to confuse developers looking at the API contract.

The code snippet below contains the root Tag Object in an API contract. Notice how the Validations tag has been duplicated, and the second definition contains a different description to the first:

tags:
  - name: Diffs
    description: Diff summary of changes in the API
  - name: Versions
    description: Deploy your API contracts
  - name: Validations
    description: Check & validate your API contracts
  - name: Hubs
    description: Interact with your Hubs
  - name: "Documentation change"
    description: Check & validate your API contracts
  - name: Validations
    description: Validate your API status

These duplicate tags would confuse anyone trying to understand your API contract, as they wouldn't know which of the two tag definitions an endpoint belongs to.

Instead, make sure you define and describe every tag only once in the root Tag Object, like in the snippet below:

tags:
  - name: Diffs
    description: Diff summary of changes in the API
  - name: Versions
    description: Deploy your API contracts
  - name: Validations
    description: Check & validate your API contracts
  - name: Hubs
    description: Interact with your Hubs
  - name: "Documentation change"
    description: Check & validate your API contracts

Define All Your OpenAPI Tags in the Root Tag Object

The OpenAPI specification doesn't require you to define all your tags in the root Tag Object of your API contract. This means you can add a tag to an endpoint without listing it in the root Tag Object, but this is a bad idea. You won't be able to control what order the OpenAPI tags should appear in, and you won't be able to add a description or provide a link to external documentation for that tag. It can also confuse developers browsing your API contract as they won't see a list of all the tags used in the API contract.

As an example, consider the code snippet below where the Previews and the Ping tags has not been included in the root Tag Object:

tags:
  - name: Diffs
    description: Diff summary of changes in the API
  # Missing Previews tag
  # Missing Ping tag
  - name: Versions
    description: Deploy your API contracts
  - name: Validations
    description: Check & validate your API contracts
  - name: Hubs
    description: Interact with your Hubs



paths:
  /diffs:
    post:
    tags: [ Diffs ]
  /diffs/{id}:
    get:
    tags: [ Diffs ]
  /hubs/{hub_id_or_slug}:
    get:
    tags: [ Hubs ]
  /versions:
    post:
    tags: [ Versions ]
  /validations:
    post:
    tags: [ Validations ]
  /previews:
    post:
    tags: [ Previews ]
  /previews/{preview_id}:
    put:
    tags: [ Previews ]
  /versions/{version_id}:
    get:
    tags: [ Versions ]
  /ping:
    get:
    tags: [ Ping ]

When you generate the documentation, notice how the Previews and Ping sections are at the bottom of the list.

This incorrect ordering and lack of description will make this section much harder to understand for a developer consuming your API.

On the other hand, notice how every endpoint in the API contract below has a tag also defined in the root Tag Object:

tags:
  - name: Diffs
    description: Diff summary of changes in the API
  - name: Ping
    description: Check the API status
  - name: Previews
    description: Preview changes to an API Documentation
  - name: Versions
    description: Deploy your API contracts
  - name: Validations
    description: Check & validate your API contracts
  - name: Hubs
    description: Interact with your Hubs



paths:
  /diffs:
    post:
    tags: [ Diffs ]
  /diffs/{id}:
    get:
    tags: [ Diffs ]
  /hubs/{hub_id_or_slug}:
    get:
    tags: [ Hubs ]
  /versions:
    post:
    tags: [ Versions ]
  /validations:
    post:
    tags: [ Validations ]
  /previews:
    post:
    tags: [ Previews ]
  /previews/{preview_id}:
    put:
    tags: [ Previews ]
  /versions/{version_id}:
    get:
    tags: [ Versions ]
  /ping:
    get:
    tags: [ Ping ]

By doing this, your documentation will display the endpoint groups in the correct order along with the tag’s description.

Conclusion

In this article, you learned more about OpenAPI and AsyncAPI tags and their value in an API contract. You also learned that you can add descriptions and external documentation links to the tag. This article has also shown you some best practices to follow when using tags that can improve the quality of your generated documentation.

Bump.sh OpenAPI and AsyncAPI documentation generator implement tags to help you keep your API documentation organized. Bump also detects and notifies you of breaking changes when deploying a new version of your API.

Bump.sh is the simplest way to automatically create API portals for internal, partner, and public APIs. Discover it by signing up.

Author: Ivan Kahl

DEV Community: Bump.sh

JSON Streaming in OpenAPI 3.2

JSON Streaming

Streaming with OpenAPI

itemSchema

itemEncoding

Popular Streaming Formats

JSON Lines & NDJSON

JSON Text Sequence

Server-Sent Events (SSE)

Sentinel Events

Conclusion

Top 5 API documentation tools

Bump.sh

Scalar UI

Stoplight Elements UI

ReadMe

OpenAPI 3.1 - The Cheat Sheet

An AsyncAPI Example: Building Your First Event-driven API

Why Use Event-driven APIs?

Implementing a Node.js Event-Driven API with AsyncAPI

1. Create an AsyncAPI File

2. Generate the Application Code with AsyncAPI Generator

3. Test the AsyncAPI Node.js Application

Using Bump.sh with AsyncAPI

Conclusion

AsyncAPI vs. OpenAPI: Which Specification Is Right for Your App?

Synchronous vs. Asynchronous APIs

Choosing Between OpenAPI and AsyncAPI

Protocols

Simplicity of Implementation

Community Support

Use Cases

RESTful APIs

Internet of Things

Combining Synchronous and Asynchronous APIs

Documenting in Any Case

So… Which one to pick?

Creating an API with Express.js using OpenAPI

Crash Course in Express

The Case for OpenAPI

Implementing an API with OpenAPI and Express

Prerequisites

Creating an Express Application

Integrating OpenAPI with express-openapi

Running and Testing the Application

Using Bump.sh for Documenting Your Express APIs

Configure Bump.sh for Express Applications

Automate API documentation update with Bump.sh

Conclusion

A Developer's Guide to API-First Design

Why Is API-first Design Important?

Faster Development Times

Improved Developer Experience

Better Collaboration and Communication

When is API-First the Wrong Approach?

The API-First Design and Development Process

Define

Design

Develop and Document

Test

Secure

Deploy

Observe

Evolve

Developer API Tools

Conclusion

API Contracts - an Extended Introduction

Why Are API Contracts Important?

What Are API Contracts ?

What Should You Consider When Designing an API Contract?

API Contracts: Best Practices

Defining the Expected Behavior of the API

Specifying the Contract and API Version

Document Data Formats, Limitations, and Restrictions

API Contract at the Age of Automation

What’s Next for your API Contract ?

Creating Better API Architecture Diagrams

What are API Architecture Diagrams and Do You Need Them?

Types of API Architecture Diagrams