Using curl to explore an API

Learning what an unfamiliar API action does is often hard. I have tried various things to speed up my learning process, but the only thing that I have found to be working for me is to test each interaction with the API by hand. I like to mess around with an API before I actually write any code or implement a feature. One good way to get a quick and easy glimpse of what I can expect from an API is to send some curl request and experience the action’s response in the most straightforward way possible.

There are lot of things I can learn from exploring an API this way. I can get a solid feeling about the complexity of the API, to know is it hard to explore new actions, and if the whole API uses a consistent structure or if every interaction with it has a unique way to communicate it’s response. Needless to say, I prefer consistency over uniqueness, and an API that leads me to explore it in more details.

I encourage everyone to test out even their own APIs this way, it can do wonders if you explore your own API from a consumers standpoint.

Installing curl #

Before using curl you need to install it. If you are on a Ubuntu machine you can just use the command bellow, or a similar command suitable for your environment

sudo apt-get install curl

GET requests with curl #

Personally, I like to start out with the GET actions. They should be side effect free and I can safely assume that I won’t do any big harm by testing them first. If that is not the case, I am clearly testing a badly designed API that I should probably stay way away from.

To send a GET request to a server I would usually write the following

curl www.example.com

But if there is a possibility that this server will redirect me somewhere else I will probably prepend it with the -L command that tells curl to follow that redirect

curl -L www.example.com

If I want to save the output to a file, I can just as easily append on -o option followed by the name of the file I want to save the content to

curl www.example.com -o my_file.txt

POST requests #

The simplest way to send data to a server I know is to use the --data parameter

curl --data "Hello, there!" www.example.com

That is of course simple, but not very practical, because I usually want to send JSON data, but it can be simulated quite easily

curl --data '{"message": "Hello, there!"}' www.example.com

Be aware, that if you want to include an environment variable in your JSON data you need to use double quotes instead of single ones. That is because bash replaces variables with their values only inside double quoted strings. Unfortunately, that means you need to escape every " with a backslash in your JSON like this \"

export MESSAGE="Hello, there!"

curl --data "{\"message\": \"$MESSAGE\"}" www.example.com

The above example is really ugly, but hey, it is working and it is way faster and easier than writing a ecstatically nicer script or to run a visual tool. So I have accepted it as a necessary evil.

Other types of requests with cURL #

Just as easily like sending a POST request you can send PUT, PATCH or DELETE request. The trick is to prepend the above POST command with an -X option and to define the action I want to use with this request.

curl -X POST --data '{"message": "Hello, there!"}' www.example.com

curl -X PUT --data '{"message": "Hello, there!"}' www.example.com

curl -X DELETE --data '{"message": "Hello, there!"}' www.example.com

curl -X PATCH --data '{"message": "Hello, there!"}' www.example.com

Summary #

As you can see, the curl command is quiet friendly and easy to use. The documentation can sometimes look scary and sometimes it feels like there is a lack of real life examples, but the curl command can be one of your best command line pals if you give it a chance. So, now, go out there and curl the net like a pro.