Available technologies and protocols
Read on to learn more about the most relevant technologies and protocols that you can use to build API products. It would help if you didn’t restrict yourself to using web APIs. Instead, you should build the API product that best reflects the needs of your users, and to do that, the more knowledge you have about what’s available, the better. This section offers detailed information about the different API technologies, the communication protocols, and the tools that are considered important to someone building an API product. Let’s start by splitting the knowledge into the areas of communication protocols, implementation technologies, and tools.
Communication protocols
Among the available communication protocols, the ones that are most overlooked are the ones that run on local networks. Usually, local network protocols help Internet of Things (IoT) devices and applications communicate. These protocols use a low amount of power to preserve the batteries of the devices that they support. Among IoT protocols, you have one called Zigbee. This protocol is an IEEE 802.15.4-based specification and is used by popular home automation companies. Philips Hue, for instance, uses Zigbee to power communication between lamps and other devices. Indesit, a house appliance manufacturer, uses Zigbee to adjust its washing machines’ cycle starting time according to the price of electricity. Yale, one of the oldest locks companies, uses Zigbee to control its smart door locks. Samsung, a technology manufacturer, uses Zigbee to let you control and monitor its smart refrigerators. If you’re thinking about building an API product that interacts with a local device, then a protocol similar to Zigbee might be a good choice.
Even though Zigbee has been gaining popularity, the fragmentation of local connectivity protocols is something to pay attention to. For that reason, a group of organizations created a new standard called Matter. Among the organizations behind Matter is, in fact, Zigbee. Matter’s goal is to help new product builders adopt a communications standard that they know will work with a vast array of products.
Let’s now focus on communication protocols that operate on the internet. While local network protocols solve challenges related to power consumption and interoperability, internet protocols are more focused on the reliability of communication. Reliability, in this case, means the ability to consistently transport information between a user and a server. Users unknowingly engage with servers while they’re performing their online activities. The protocol behind most online activities is the Hypertext Transport Protocol, or HTTP. From a user perspective, it’s as if the information is right in front of you, being displayed on the screen of the device that you’re using. From a communication perspective, information is traveling across the world using the internet to arrive at your device and then be displayed. HTTP is behind that communication and translates what users request into commands that are sent to servers. The web is powered mostly by HTTP, and when you refer to APIs, most of the time what you’re referring to are web APIs.
In summary, HTTP is the protocol behind most of the available APIs. HTTP is a protocol that works in a synchronous way. In other words, when users request something, the information is sent to a server, and the client waits until a response is available. The response might become available almost immediately, in which case the interaction feels like it’s happening immediately. Or, in some situations, it might take longer for a server to produce a response. Other protocols have been created to handle situations where the user doesn’t need a response immediately or the user doesn’t want to wait for a response to become available. Those protocols handle what is called asynchronous communication.
Among the available asynchronous ways of communicating, you have the Advanced Message Queuing Protocol, or AMQP. This is a protocol that is primarily focused on handling queues of messages. A queue of messages is a group of pieces of information that are stored in a specific order. Each message is picked from the queue and processed one after another. Messages can contain any information and can be used in a variety of patterns that enable multiple kinds of products. You can have messaging patterns that let users perform a command asynchronously. Other patterns are used to let users receive notifications on their devices. There are even patterns that let a server broadcast messages to a group of users without having to connect to each user individually. The important thing to retain about AMQP is that it lets you create interactions that don’t require an immediate response from the server.
Another asynchronous protocol that is popular among IoT products is Message Queuing Telemetry Transport, or MQTT. This protocol focuses on being lightweight in the information it needs to let messages flow from a server to a client. MQTT was built to be as simple as possible and enable low-powered devices to subscribe to information that servers make available. Before, you saw how IoT devices can communicate synchronously inside a local network using Zigbee. In this case, MQTT enables those devices to send and receive information to other devices in an asynchronous way.
Implementation technologies
Now that you know what the available communication protocols are, let’s see which technologies you can use to build API products. Starting with local networks, the technologies that you can use either work on top of protocols such as Zigbee or something at a higher level such as HTTP or MQTT.
Let’s start with Zigbee. The Zigbee protocol describes three types of devices that can operate on the network. You can build a Zigbee coordinator, a router, or an end device. The Zigbee coordinator manages communication between other types of devices. It can also serve as a bridge between Zigbee and other types of networks, such as the internet. The Zigbee router is responsible for making sure that the information flow reaches all the devices present in the network. Finally, Zigbee end devices are the final nodes in the network. You can build on top of the Zigbee protocol by using—or asking your engineering team to use—one of the available frameworks. The Connectivity Standards Alliance (CSA), formerly known as the Zigbee Alliance, offers documentation and pointers to implement solutions for Zigbee and also for the Matter protocol. Operating systems such as Tizen offer direct support for Zigbee to applications built to run on it.
Moving into internet technologies, let’s look at what you can build on top of HTTP. Anything that runs on top of HTTP is understood as “the web.” Fortunately, there are plenty of technologies and approaches to building web APIs. From frameworks to API specifications, you have a lot to choose from. There may be many solutions because the web itself is the most used communication platform. To begin with, most programming languages offer a way of building a web API from scratch. For instance, Node.js, a popular programming language, has the Express.js framework. Python, another language, offers Flask and FastAPI. And there are other options for languages such as Java or PHP. You can pick the language and framework that best fits your needs and where you or the engineers that work with you feel more comfortable.
To specify the API that you’re building, you also have different options. In this case, depending on the type of web API that you’re building, you have different specification standards. OpenAPI is the preferred specification for REST APIs. While REST restricts your API consumers to the resources and operations that you make available, you can offer more generic access through GraphQL. Essentially, GraphQL lets your API consumers access the data that you are exposing as a graph. In other words, you don’t have to provide all the queries and operations beforehand because consumers can navigate the data itself. If you’re concerned about performance and data validation, you can use the gRPC specification. With this approach, you have a specific format for the information that is shared between consumers and servers, making the communication stricter than with the REST approach. All these technologies provide a synchronous communication solution. Read on to learn how you can build asynchronous APIs.
If the API that you’re building doesn’t require an immediate response, or if the operation that you offer takes too long to process, then you can think of offering an asynchronous solution. Asynchronous APIs usually make use of two communication channels. One of the channels is used by the API consumer to send information to the server. The API consumer uses this channel to execute an operation on the server or to request certain information. The second channel is used by the server to communicate the result of the request back to the consumer. Those two channels can coexist on the same type of network or can use totally different approaches. One example of a second channel that runs on top of HTTP is called Webhooks.
With Webhooks, you ask the API consumer to provide a way to receive a request from the server. When the server has information to be shared with the consumer, it uses the Webhook URL to push the available data. The consumer then receives the request and the information that they were waiting for. Another way of building an asynchronous API on top of the web is to use something called WebSockets. In this case, the API will be used by web browsers to communicate with the server. The goal is to open a direct communication channel that can be used by both the browser and the server to send information in both directions. This will allow the server to send information to the browser asynchronously. As an example, this is how some solutions, such as browser notifications, are implemented.
If we now move to other asynchronous protocols, there are different products that you can use. RabbitMQ is a product that provides an asynchronous communication broker that runs on the AMQP protocol. Mosquitto is another broker that in turn runs on MQTT. Another product that provides asynchronous messaging solutions is Kafka. Even though Kafka uses its own communication protocol and message format, it’s worth mentioning because it’s one of the most used asynchronous solutions.
Tools
By now, you know about the protocols, formats, and technologies that are available to help you build an API product. Continue reading to learn about the tools that you can use to get your API up and running. You have tools that let you design and define how your API will behave. Other tools help you validate your API and offer a mockup. There are also tools that convert your API definition into running code that can be deployed to a running server. Whichever tool you use, remember that it doesn’t replace your knowledge. You should be able to do things on your own by understanding the principles and the theory behind your actions. Let’s start by looking at API design tools. These are usually web applications that help you create an API definition document. These are important to you because they help you build your API product during the first stages of the process.
One of the most popular API design tools is Postman. This is a web and desktop application that can be used individually or by different members of a team to collaborate. Postman offers an interface that lets you create API definitions and automatically runs validation checks to make sure that your API follows industry best practices. With Postman, you can create an API mock from your API definition. You can share a link to the mock with your potential customers and use it for validating your API design. Your API clients can use the mock to try making requests to the API and seeing what it looks like before you actually release any product.
Another tool in the area of API design is Stoplight. The company offers a web and desktop application that lets you design and document your API. Among its features is the possibility of generating and customizing API portals to offer onboarding and documentation to developers. API design is the strong offering of Stoplight. It offers a unique visual approach to designing an API. Instead of typing your OpenAPI definition into a text editor, you can visually configure how your API will behave.
Swagger is probably the oldest API design tool still available. It offers a web application that lets you design your API by writing its OpenAPI definition. Even though it uses a text editor, it automatically renders the result of what you’re typing. You can interactively write your API definition and see the results immediately as API documentation. That’s an interesting approach because it gives you the perspective of what your API consumers will view.
Another area that is interesting to you is API documentation. API documentation gives you the ability to explain to your users what your API does and how they can use it. There are several tools in this area, ranging from simple documentation generators to more sophisticated API portals. In fact, all the aforementioned API design tools also allow you to publish API documentation. However, there are other tools that are more focused on API documentation.
One such tool is ReadMe. This is a web application that lets you build interactive API documentation. Anyone that accesses your API documentation will be able to interact with the API and engage with you, or your support team, if needed. It also lets you, the API owner, interact with your users by sharing updates whenever something changes. With ReadMe, you don’t have to install anything as the tool hosts the whole documentation.
Another tool that lets you build your API portal is Apiable. This lets you create your API documentation and goes further by letting you manage the signup and onboarding process. Apiable also lets you create what it calls “API products.” This feature lets you define signup processes and subscription plans for your API. Apiable manages the process so that you can focus on building and maintaining your API.
If you prefer to use an open source tool that you can run on your machine, you can look at Redoc. This is a tool that generates documentation from an OpenAPI definition document. Redoc follows a popular three-panel page layout with features such as a search bar and API request and response examples. You can install it on your machine and run it every time you update your OpenAPI definition.
The tools that I presented here are meant to be examples of what is available. Keep in mind that tools change—what’s important is that you stay updated with what exists. No tool can replace your own knowledge and how you’re able to build and maintain your API. However, having the right tools at hand makes your job much easier and more pleasant.
