use-bash-and-curl-to-get-response-code-from-API

Using cURL in a Bash Script: Get the Response Code from an API

Using the cURL command in a Bash script can be useful, but why?

We live in the era of APIs…

…you ask for data and you get it back…

But how can you know if your API request is successful?

HTTP response codes are able to tell you that, for example a successful request is identified by a 2xx code.

A 200 response is a very common 2xx response code that you receive when you request data from an API and the API successfully returns data back to you.

In this article I want to show you how you can use Bash and cURL to call an API and confirm if the call was successful by reading the HTTP response code.

What is cURL?

This is a tool to request data from a server or to transfer data to a server, using multiple protocols and the protocol we are interested in is HTTP (or HTTPS depending if you connect to an API protected by SSL).

The cURL command can be used in Linux in many different ways (e.g. to download files).

Here we will use cURL to retrieve weather information for London via the Open Weather API.

The sample API URL we want to call is:

https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22

And using cURL:

curl "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22"

The response we get is in JSON format:

{"coord":{"lon":-0.13,"lat":51.51},"weather":[{"id":300,"main":"Drizzle","description":"light intensity drizzle","icon":"09d"}],"base":"stations","main":{"temp":280.32,"pressure":1012,"humidity":81,"temp_min":279.15,"temp_max":281.15},"visibility":10000,"wind":{"speed":4.1,"deg":80},"clouds":{"all":90},"dt":1485789600,"sys":{"type":1,"id":5091,"message":0.0103,"country":"GB","sunrise":1485762037,"sunset":1485794875},"id":2643743,"name":"London","cod":200}

JSON (JavaScript Object Notation) is with XML the most common data format used by APIs to exchange data.

As you can see the response contains data about pressure, humidity, temperature, etc…

The HTTP Response Code

As I said before we want to understand if a call made via cURL is successful.

For that we need to analyse the HTTP response code of the response we receive when our request is submitted.

The cURL –write-out flag can be used to write the HTTP response code to the shell:

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" 

And the response is:

{"coord":{"lon":-0.13,"lat":51.51},"weather":[{"id":300,"main":"Drizzle","description":"light intensity drizzle","icon":"09d"}],"base":"stations","main":{"temp":280.32,"pressure":1012,"humidity":81,"temp_min":279.15,"temp_max":281.15},"visibility":10000,"wind":{"speed":4.1,"deg":80},"clouds":{"all":90},"dt":1485789600,"sys":{"type":1,"id":5091,"message":0.0103,"country":"GB","sunrise":1485762037,"sunset":1485794875},"id":2643743,"name":"London","cod":200}200

You can see the HTTP response code at the end of the response, so we are getting near to what we want.

But, how can we remove the JSON data from the response?

We can use the –-output flag that allows to write the output of the cURL command to a file instead of stdout. So let’s write the output to a file called output.txt

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                  Dload  Upload   Total   Spent    Left  Speed
100   459    0   459    0     0   2521      0 --:--:-- --:--:-- --:--:--  2550

200 

A lot better…

And what if we want to use the –output flag to avoid showing the JSON response but at the same time we don’t want to create the file output.txt?

How would you do it?

Let me know in the comments below!

The last thing we want is not to show the transfer report for cURL that was present in the previous output.

To do that we can use the –silent flag.

curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt --silent
200

And voilà, we just got the HTTP response code.

It’s a 200 that represents a successful request.

Using cURL in a Bash Script

Let’s write a Bash script called http_response.sh that writes the output of the cURL command to a variable and then prints the value of the variable to the shell:

#!/bin/bash
   
HTTP_CODE=$(curl --write-out "%{http_code}\n" "https://samples.openweathermap.org/data/2.5/weather?q=London,uk&appid=b6907d289e10d714a6e88b30761fae22" --output output.txt --silent)
echo $HTTP_CODE 

When we run the script we get the HTTP response code back:

localhost$ ./http_response.sh 
200 

Conclusion

In this article you have learned how to:

  • Use the cURL command to retrieve data from an API (or from any URL in general)
  • Print the HTTP response code
  • Integrate cURL into a basic Bash script that can be enhanced based on your requirements.

Does it make sense?

Let me know if you have any questions 🙂

And if you want to learn more about curl, here you can see how to download files using curl.


Related FREE Course: Decipher Bash Scripting

Share knowledge with your friends!

5 comments

  1. After going over a number of the blog posts on your web site,
    I really like your technique of blogging. I book-marked it to my bookmark website list and will be checking back in the near future.
    Please visit my website as well and tell me your opinion.

  2. Good post. I learn something totally new and challenging on blogs I stumbleupon every
    day. It’s always exciting to read through content from other writers and practice
    a little something from their sites.

Leave a Reply

Your email address will not be published. Required fields are marked *