CLI for REST APIs

CLI for REST API

Command line interface for backend services is not always considered a required item in the production readiness checklist. Why do we need to spend additional time if we already have swagger documentation, postman collection, end-to-end tests, and a UI application? REST APIs are built for developers, and technical documentation should give all the required information to understand how it works. 

Yes, but a CLI application can provide the user with the experience to answer most of the questions very quickly. Together, with good documentation, it brings the fastest way of integration between two parties. Also, CLI applications can significantly simplify REST API interactions by hiding complexity and encapsulating authentication mechanisms. Lets, for example, create a simple CLI application for google APIs to get user emails.

Welcome Page

This is the welcome page of a GLI application. The example is of the command line interface for Google API services.

The same as a web home page the cli command can also have a welcome page shown using basic command execution. You can find some contact information and a pretty ANSI logo here.  

Authentication

CLI applications can simplify the authentication process. Authentication in third party services using a browser is a workable flow for CLI as well. Just run the login command, provide all required permissions for the app, and you can start playing with REST. For example, this is how Google auth works together with our CLI example:

Specify a callback URL to your localhost server, start local HTTP server to listen to only this URL, and close it immediately once you get your request back. Start/stop HTTP server for this purpose using golang can be done very easily and fast. For more details, please take a look at the example source code.   

Quick User Experience and Self Discovery

According to the Standards for Command Line Interfaces, every application should support two options:
--version and --help. This makes CLI applications self-discoverable and fully documented right in place without the need to open a browser. While switching tabs between CLI and the browser is an extremely fast operation, switching your mind to browser and back could be very disruptive. This also can work as documentation for the REST API itself with working examples right into place.

Using the --help command, we can see examples of commands and try them immediately to see the actual response. Applying it to all subcommands provides all required information to work with the application. 

Automation

The great power of CLI is automation. Daily routine tasks such as reporting time in time tracker systems or sending status report emails to your manager can be replaced with CLI commands easily. Going further, mapping the CLI language to human language is simpler than GUI and also much more easily adoptable for users with disabilities.

High level end-to-end or smoke tests can be written using a number of sequential CLI commands executed one by one. Zero and non-zero return codes can be used to verify the results and stop CI/CD pipeline from further execution.   

Summary

In the early PC's days, command line applications were popular because of the lack of compute resources. This is not a case in our days. Working time of software engineers is the most valuable resource and costs burden for businesses. Imagine how many resources you can save by simplifying integrations between squads, eliminating GUI web applications for internal B2B processes and automating daily activities. With testing automation capabilities and resource savings, the pros can be tremendous.  

Github link to the example: https://github.com/nikitsenka/gli