Application Programming Interfaces (APIs ) are just one of the essential pieces of any microservice or container-based architecture. And if you’re looking for a way for different services to communicate with each other, cURL API commands can do wonders for you.
In this tutorial, you’ll learn the basics of cURL API and some practical examples of how to use it for testing and troubleshooting.
Read on and get started sending requests securely to REST APIs!
Prerequisites
This tutorial will be a hands-on demonstration. If you’d like to follow along, be sure you have the following:
- A Linux machine – This tutorial uses Ubuntu 20.04 LTS, but the commands should work on any flavor of Linux.
- cURL installed on your Linux machine.
- A REST API to test – This tutorial uses a {JSON} Placeholder, a fake online REST API. This fake API allows you to test different cURL commands without messing up a real API.
Retrieving Data via the cURL API Command (HTTP GET Requests)
API testing is essential to ensure your API works as expected. One of the most common types of API tests is an HTTP GET request. You use an HTTP GET request to retrieve specific data from a server.
To make a GET request, you need to specify the URL of the server you want to connect to. GET is the default request type, so you don’t need to specify GET explicitly.
1. Run the curl command below to make a GET request, and return all posts in JSON format.
curl https://jsonplaceholder.typicode.com/postsYou’ll get a long list of JSON objects in the output, including the userId, title, etc., as shown below.
Notice the output contains tons of posts (the list goes on), and just by looking at it, you already know that scrolling through the list feels tedious.
If you only want to retrieve a specific post or userId, jump to the following step.
2. Next, run the same command below as you did in step one. But this time, append the ?userId=1 query parameter.
Query parameters tell the curl command to extract data you specified to retrieve from a server. In this case, the curl command retrieves each post with a specific userId of 1.
curl https://jsonplaceholder.typicode.com/posts?userId=1
3. Lastly, rerun the same command below, and add the -i option to include the response headers in the output.
curl -i https://jsonplaceholder.typicode.com/posts?userId=1You can see in the output that the status code is 200 in the response headers, which indicates the request was successful.
Depending on the HTTP request methods (GET, POST, PATCH, etc.) you use, the status code will be different. Read on, and you’ll learn more about each status code.
Sending Data to Servers with HTTP POST Requests
You’ve requested data from a server by sending GET requests, but can you do the opposite and send data instead? Yes! By sending POST requests, you create new data on a server.
But it’s worth being cautious when you send POST requests. Why? Even if the data you sent via a POST request exists on the server, the POST request still overwrites the data.
Run the below command to specify (-X) a POST request to create a new post with the following data (-d), in key-value pairs separated by the & symbol:
- A
userIdof10. - A title of
Hello World. - A body of
This is the body.
curl -X POST -i -d "userId=10&title=Hello World&body=This is the body." <https://jsonplaceholder.typicode.com/posts>
This time, you will get a 201 status code in the output, as shown below. In REST APIs, the 201 status code indicates the request has been fulfilled and that a new resource/data has been created.
Updating Resources by Sending HTTP PUT Requests
So far, you have learned to retrieve and add data to a server by sending GET and POST requests. But what if you plan to update an existing resource on the server instead? In that case, sending PUT requests come into play.
Run the below command to specify (-X) a PUT request to update the data (-d) with a post ID of 1 for the userId=1.
If the resource/data to update doesn’t exist on the server, the PUT request creates a new resource with the data you provided instead.
curl -X PUT -i -d "userId=1&title=Hello World&body=This is the body." <https://jsonplaceholder.typicode.com/posts/1>
Below, you get a 200 status code, which indicates the request was successful. The server understood the PUT request and updated the data.
Now, try to run the below command to try and update the same data, but this time, without specifying the post ID number.
curl -X PUT -i -d "userId=5&title=Hello World&body=Post body." [<https://jsonplaceholder.typicode.com>](<https://jsonplaceholder.typicode.com/>)
The 404 status code in the output below indicates the resource you’re trying to update doesn’t exist on the specified server. With this example, you’ll be mindful of what’s causing the 404 status code.
You get this status code since you didn’t specify the post ID in the curl command. But an incorrect URL can also result in getting this status code.
Deleting Resource by Sending HTTP DELETE Requests
Why would you want to delete a resource from the server? There can be many reasons. For instance, if you no longer use a particular resource, you might want to delete that resource from the server to save some space.
Run the command below to specify (-X) and send a DELETE request to delete the post with an ID of 2.
curl -i -X DELETE [<https://jsonplaceholder.typicode.com/posts/2>](<https://jsonplaceholder.typicode.com/posts/2>)
Securing API with RESTful Authentication
Now that you know how to make various requests to a REST API, it’s time to learn how to use authentication with a REST API. Security is always a top priority anyway.
If you don’t authenticate with a REST API, anyone who has the URL of the API can make requests and get data from the API, which is not what you want.
There are two methods to authenticate with a REST API. You must implement any of these two methods below so that only authorized users can access the API:
- Basic Authentication – The simplest way to authenticate with a REST API. In this method, you need to send your username and password with every request you make to the API. The downside of using Basic Authentication is that your username and password are sent with every request in plain text — too risky.
- Token-Based Authentication – This method is more secure to authenticate with a REST API. In this method, you must first authenticate with the API and get a token. The token is then sent with every request you make to the API. In contrast with Basic Authentication, the benefit of using Token-Based Authentication is that your username and password are not sent with every request — more secure.
You’ll touch on Basic Authentication methods using the GitHub API so you can get an idea of how they work.
Run the below command specifying your GitHub username (-u) for Basic Authentication to make a GET request to the GitHub API. Replace your_username with your actual GitHub username.
curl -i -u your_username [<https://api.github.com/users/octocat>](<https://api.github.com/users/octocat>)
After running the command, enter your GitHub password when prompted.
You’ll get a list of the GitHub repositories for the user octocat via the GitHub API, as shown below.
Conclusion
In this article, you’ve learned essential cURL API commands for testing to work with REST APIs. You touched on sending various cURL API requests to see them in action and understand how they work.
REST APIs are everywhere nowadays. They are used by almost all the major companies, such as Google, Facebook, Amazon, and Twitter. So if you wish to work with them, this tutorial is your first step.
You’re now equipped with the basics of REST APIs, so it’s only fitting to pat yourself on the back. Now, to better understand what actually happens when you make requests to REST API, why not explore more about various types of status codes?
