CLIs and APIs are like peanut butter and jelly — beloved by their respective fans but better together. But what is a CLI? And what, really, is an API? Today, we’re going to look at this question. We’ll provide a top-level breakdown of APIs and CLIs, and point to their use cases in the modern web space.

What is a CLI?

CLIs, or Command Line Interfaces, are textual interfaces that allow a user to execute a command, manipulate data, and interface with a system. The CLI removes the need for a GUI, or Graphical User Interface, presenting a solution that’s low on resource demand and high on user control. CLIs are often one of several options to interact with a system, with the other most common option being a GUI. In the web space, CLIs provide a way to directly interact with a remote system as if you were local to that system and using a terminal.

While a CLI has traditionally required quite a bit more knowledge of the system and its underlying commands to effectively utilize, Command Line Interpreter software can enable autocompletion, allowing users to automatically complete common command line forms. Nevertheless, the absence of visual tooltips and other such instruction systems is a common trade-off for the higher control that a CLI grants a user. As such, CLIs are often preferred by “power users” who prize efficiency and power over graphical bells and whistles.

Example CLI

The AWS CLI is a great example of a CLI. This CLI is a direct way to interact with your AWS systems and allows for a great amount of control.

Let’s look at a straightforward CLI example:

aws configure --profile profilename

In this example, we are creating a profile. The way to do this is quite simple. First, we let AWS know that we are running a configuration command through the use of configure, and then we let it know what we’re configuring using the --profile input. From here, we can state the profilename, which AWS will then process.

Where the CLI really shines is in more complex functions. For each part of the command line, you can input a variety of commands and flags to generate some rather complex functionality.

aws ec2 describe-volumes --query 'Volumes[*].Attachments[?State==`attached`].VolumeId'

In this example, the CLI string will request information for all volumes within an EC2 instance, filtering them by their Attached State and displaying their VolumeID. Even though this is only slightly more complex than our first example, AWS CLI commands can be incredibly long and complex, generating high amounts of data and utility in a compact form.

What is an API?

An API, or Application Programming Interface, is a collection of definitions and protocols that allow software components to speak to each other. For a piece of software to talk with another piece of software, the two need to have a common link between them to negotiate their working relationship and to understand what each request and response actually means. For this reason, APIs are often thought of in the context of a “contract,” wherein the API sets and codifies the specific interactions between systems that should be expected and managed.

In web development, a web API is simply an API that uses the HTTP protocol as the medium for communication. Whereas an API on a computer may allow the CPU and GPU to communicate to draw a three-dimensional image on a screen using the connections on the motherboard, a web API (often just called an “API”) connects two systems in a similar way across the internet.

Example API

The United States National Weather Service API is an example of a web API. This API utilizes remote resources to serve the forecast data for a given set of coordinates. Let’s look at the weather alerts for New York, United States.

Our API call will look like this:

https://api.weather.gov/alerts/active?area=NY

By providing our area of NY, the API will utilize this prefix to locate the coordinates and report data using the proper service. The API then references internal systems to request this data from another server, resulting in an output that shows all the current weather alerts for the area of New York state.

This example is relatively simple, but the output is rather large. When run, this API request generates potentially hundreds of alerts for various cities and towns. This is often the power of an API — the ability to simply call a large amount of data for manipulation.

What’s the Difference?

What differentiates a CLI from an API is the use case and the relationship between the user and the system. APIs and CLIs are two ways an entity can access systems and data, but their general use case is very different depending on the implementation.

CLIs are powerful, but more than anything, they represent a direct connection. A CLI is meant to emulate the familiar access paradigm of sitting at a terminal, issuing a command, and receiving something in return. As such, CLIs represent a very direct route to data structures and systems, which is one of the reasons they’re often reserved for power users. A CLI is typically an unfiltered mainline, for better or for worse, with both an exceptionally low barrier of entry and an extremely steep learning curve.

APIs, on the other hand, can be equally powerful but often form a type of layer between the requester and the underlying system. Using a CLI is like walking into a store and grabbing an item off the shelves. An API is more like asking the staff to get the item for you based on your shopping list requirements. There’s quite a bit more support and help involved, which can be great, but it can also be somewhat of a slower process when all you really need to do is just walk in for an item.

That being said, it’s important to note that the line between API and CLI has gotten very blurry over time. There is a spate of APIs that function very similarly to CLIs, allowing remote access to underlying resource states and systems, obfuscating the reality of their API form and function with a CLI-like experience. CLIs have also seen API-like functionality such as pagination and contextual feedback pop up here and there, reducing the overhead of an API while promising a better experience than CLI purists might expect.

Ultimately, the difference here is the form and function of the use case. Do you need direct access to a system without a complex layer of conversion of mutation? A CLI is probably your best bet. We can see this bear out with the modern cloud, wherein CLIs are a driving force behind the creation and maintenance of cloud-based systems worldwide. But what if you need something more? Do you want to know last week’s weather in Liverpool represented in JSON format? A CLI might be able to do this — with many, many layers of additional request flags — but an API is more likely to serve this single-use data in a parseable way.

Conclusion

The web is driven by CLIs and APIs. At some point, if you develop on the web, you have likely used one or the other. The reality is that CLIs and APIs are opposite sides of the same coin, and they are powerful options for specific use cases across the board. In the modern web space, this is becoming less and less an argument of either a CLI or an API, and more a discussion of a CLI and API working in tandem. Adopting both these approaches, or at the very least supporting them, can deliver strong benefits to any web product.