Invoke Your REST APIs with HTTPie
HTTPie is a command-line HTTP client for interacting with HTTP servers.
HTTPie (pronounced as aitch-tee-tee-pie) is a command-line HTTP client to make CLI interaction with web services as human-friendly as possible. It can be used for testing, debugging, and generally interacting with HTTP servers. HTTPie provides a simple
http command that allows for sending arbitrary HTTP requests using a simple and natural syntax and displays beautifully colorized output.
In this tutorial, you will learn how to use this tool to access REST services.
As a modern command-line tool, HTTPie offers several noteworthy features:-
- Simple, expressive and intuitive HTTP command syntax
- Nicely formatted and colorized terminal output
- Out-of-box JSON support
- Forms and file uploads
- Support for custom HTTP header
- Major OS supports — Linux, macOS, and Windows
- Supports arbitrary request data
- Plugins to support additional features
Throughout this article, you’ll see the usage of these features.
HTTPie can be installed through several means.
brew install httpie
apt-get install httpie
pip install --upgrade pip setuptools
pip install --upgrade httpie
Now that HTTPie is installed in the local machine, it can be used to invoke all sorts of HTTP methods. This section will demonstrate various usage of the
In this section, we will use the following websites to demonstrate the aforementioned features:-
- http://example.org/ This a sample website to try the basic HTTP commands
- http://httpbin.org/ This is a simple HTTP Request & Response Service
- https://jsonplaceholder.typicode.com A placeholder website to invoke REST APIs
HTTPie provides the
httpcommand to access HTTP servers. Following is an example of executing the
http command. This provides HTTP headers and other server information.
The most frequently HTTP operation is to retrieve information or other resources from a server. HTTP GET method facilitates this operation. An HTTP GET request can be with or without additional query parameters.
Following is an example to use the GET method with HTTPPie without any additional query parameters:-
http GET http://httpbin.org/get
However, it is quite uncommon to invoke GET requests without query parameters. This can be done by appending the parameters in param==value format in the original request.
The following example demonstrates this. In this, we are fetching all posts with userId as 1.
http https://jsonplaceholder.typicode.com/posts userId==1
Following is an example of multiple query parameters:
http https://jsonplaceholder.typicode.com/posts userId==1 id==1
It is quite common to supply several HTTP headers to provide additional information to the server. In HTTPie, we can add HTTP headers using the Header:Value format. This is demonstrated below:
http example.org X-Foo:Bar Sample:Value
Posting and Updating Data
The HTTP POST method is used to create new data on the server. HTTPie supports the POST method and facilitates several modes to deliver the payload in JSON format based on certain request headers. The following example demonstrates the usage of the POST method where JSON data is supplied inline. In this non-string parameters are formatted as Param:=Value
http POST https://jsonplaceholder.typicode.com/posts title=foo body=bar userId:=9
The HTTPPie also allows us to embed the JSON data in a file and provide it in the command. This is shown as below:
HTTP PUT command is used to update the already existing data in the server. As demonstrated in the POST method, in a similar manner, the HTTP PUT command can be used to update the data:
http PUT https://jsonplaceholder.typicode.com/posts/10002 firstname.lastname@example.org
The HTTP DELETE is used to delete resources in an HTTP server. Following example demonstrated the usage of the delete method:
http DELETE https://jsonplaceholder.typicode.com/posts/1
Authentication with HTTPie
The previous section demonstrated the usage of core HTTP methods using HTTPie. But in all of these examples, we assumed that application resources are accessible without any sort of authentication. But in a real-life application, that's rarely the scenario. Most applications are secure and enforce its users to authenticate before accessing the offered resources.
All modern HTTP client applications provide excellent support to use various authentication modes and HTTPie is no exception to that. It offers support for the major authentication types — Basic, Digest, and Password prompt.
Accessing resources using Basic authentication
HTTP Basic Authentication is an authentication scheme in the HTTP protocol. In Basic Authentication, the HTTP Authorization header is set to Basic and username and password are supplied in cleartext. Basic authentication always needs to be used other secure mechanism such as HTTPS
Following example demonstrates accessing a server resource that mandates the user to authenticate through HTTP Basic Authentication:
Note the return code is 401 UNAUTHORIZED, username and password is not supplied with the request. The HTTPie allows using basic authentication by supplying username and password with -a username:password format. This is demonstrated below.
Accessing resources using Digest authentication
The major issue with the Basic authentication is it let the username and password transported to the server in plain text. Digest authentication takes a slightly different approach. In digest authentication instead of plaintext mode, it takes a hash-based approach to share the credentials with the server. Following are the sequence of steps in digest authentication:-
- Client requests a resource from the HTTP server
- The server responds with a special code known as nonce and a string known as realm and asks the client to authenticate
- The client responds with the previously shared nonce and a hashed value of the username, password, and realm
- The server authenticates the client with the provided details and shares the requested resource if authentication succeeds
HTTPie allows digest authentication with -A Digest flag in addition to -a username:password as shown below:
HTTPie also supports additional authentication mechanisms in terms of plugins. For example, it supports jwt-auth, OAuth, NTLM, AWS-auth to name a few.
HTTPie is a light-weight but extremely powerful tool to communicate easily with an HTTP server. The ability to invoke a variety of HTTP methods with an HTTP command and other sensible default values makes it a perfect candidate in RESTful and microservices ecosystem