What is cURL?

Application Programming Interfaces (APIs) are an essential part of the web. These tools allow you to interact with other platforms.

For example, you can use the Twitter API to post Tweets or display a list of Tweets on your timeline. You can use the Airtable API to access your spreadsheets on Airtable and add new records. But, how do you actually interact with APIs?

One of the most common ways to interact with an API is through cURL, a command line tool that allows you to make web requests. It’s likely most APIs you’ve seen in your history as a developer will have included at least some documentation on how to use cURL with their API.

In this guide, we’re going to discuss what cURL is and how you can use it to make a web request. We’ll also walk through a few basic curl commands to help you get started.

What is cURL?

cURL stands for “client URL” and is a command line tool that allows you to interact with websites. You can use it to make any type of web request. This means you can use cURL to get information from APIs, download webpages or submit data to an API.

cURL comes installed on most UNIX-based operating systems, so unless you are running an Apple II, then you probably already have the package installed. When you use cURL as a command, you don’t need to capitalize the term: just use the command curl.

How to Make a Request Using cURL

In this tutorial, we’re going to discuss how to use cURL to retrieve information from the Airtable API. This API allows you to view, create and amend records in an Airtable database, which is similar to a spreadsheet. Our Airtable document contains a list of teas with some tasting notes.

The Airtable API provides two options you can use to interact with their API: cURL or JavaScript. Of course, we’re going to focus on the cURL option in this tutorial.

Make a GET Request Using cURL

To make a cURL web request, we only need to specify “curl”, followed by the URL that we want to retrieve. If we want to make a GET web request to the Airtable API, we could use this command:

curl "https://api.airtable.com/v0/appiTz7oLBs9hDIFg/Tracker?maxRecords=3&view=Grid%20view"

When this command is executed, the following is returned:

{"error":{"type":"AUTHENTICATION_REQUIRED","message":"Authentication required"}}

Our cURL command has successfully made a web request! The problem is that we haven’t yet specified an API key, which we must use to authenticate ourselves. To do so, we are going to follow the instructions on the Airtable API and specify an “authorization” header:

curl "https://api.airtable.com/v0/appiTz7oLBs9hDIFg/Tracker?maxRecords=3&view=Grid%20view" -H "Authorization: Bearer YOUR_API_KEY"

When we run this command with an API key, the following is returned:

{
   "records":[
      {
         "id":"recyPfUXJUP1HH03a",
         "fields":{
            "Drink":"Black Decaf Tea",
            "Date":"2020-05-24T10:03:38.000Z"
         
},
         "createdTime":"2020-05-24T10:03:38.000Z"
      ]
}

As you can see, cURL has returned a list of the records in our database. Right now, we only have tasting notes for one tea, but that’s all we need to show that our cURL command has worked. 

Make a POST Request Using cURL

cURL also supports making HTTP POST requests. This allows you to submit data to a web server which will be processed by that server. In the case of the Airtable API, a POST request allows you to add a record to a database. Airtable gives us the following command as an example:

curl -v -X POST https://api.airtable.com/v0/appiTz7oLBs9hDIFg/Tracker \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "records": [
    {
      "fields": {
        "Drink": "Darjeeling"
      }
    },
  ]
}'

There’s a lot going on in this command, so let’s break it down:

• -v tells cURL to show us all the details of the output.
• -X POST tells cURL to make a POST request.
• https://api.airtable.com/v0/appiTz7oLBs9hDIFg/Tracker is the URL to which we are sending our post request.
• -H allows us to specify headers for our web request, which store additional data such as our API key and the type of content we are sending.
• –data is where we specify the data we want to send to the web server.

Executing this command returns the following:

{
    "records": [
        {
            "id": "recyPfUXJUP1HH03a",
            "fields": {
                "Drink": "Darjeeling",
                "Date": "2020-05-24T10:03:38.000Z"
            },
            "createdTime": "2020-05-24T10:03:38.000Z"
        },
}

Our command worked! We successfully used cURL to make a POST request to the Airtable API.

Wrapping Up

cURL may not be the most intuitive tool in the world, but it does make an excellent candidate for interacting with APIs.

There are a number of tools out there you can use instead of cURL, such as Postman or Insomnia. These tools provide a graphic user interface that makes it easy to customize your web requests. In addition, if you’re building a web app, you’ll probably want to make a web request using code in a language like Python.

However, the main advantage of using cURL is that it helps you figure out how to structure your web requests before you add them to your application. You can try out different methods and make sure a request is valid before actually coding it into your application.

If you want to learn more about how the curl command works, check out the man page on curl by running man curl in your Linux command line.