How to Use cURL with REST API

cURL, also known as Client URL, is a command line utility. This CLI tool facilitates data exchange between a device and a server through a terminal. By using cURL, you can make network requests and send or receive data directly from the command prompt without needing a GUI. 

cURL also has various options which enable users to add custom headers, specify timeouts and authentication details, etc. The simplicity of using cURL from the command line attracts a lot of developers to use it as their go-to tool for testing APIs and microservices. Additionally, its support for the HTTP protocol makes it convenient for testing REST APIs.

In this tutorial, you’ll learn how to interact with the REST API using cURL. You’ll also see how to set up and use a proxy with cURL. Let's get started.

Tutorial: Using cURL with APIs

In this section, you’ll explore various cURLs commands by interacting with the REST API. If interested, you can also check our cURL converter tool to transform cURL commands into your preferred programming languages. You’ll also learn how to utilize Oxylabs’ Web Unblocker with cURL. It’s an AI-powered proxy solution that enables you to send network requests without exposing your IP address and other personal tracking information.

1. Preparing the environment

First, install cURL if you don’t have it already. You can install it with the following command in Linux:

apt install curl

If you’re using a different operating system, you can download and install the latest version from the official website. Once you’ve installed cURL, try running the below command in your terminal:

curl --version

The above command shows the version, release date, supported protocols, and features of your cURL executable.

2. Create an Oxylabs account

To get started, take advantage of the 1-week free trial. It’ll give you sufficient time to explore various Web Unblocker features and ensure it meets your needs. If you decide to continue using Web Unblocker after the trial period, you can easily upgrade to a preferred plan without any interruptions in your service.

Upon selecting your preferred plan, you’ll receive sub-user credentials that’ll enable you to send network requests through the proxy.

3. Set up Web Unblocker

Set Web Unblocker as a proxy using the -x flag of cURL. The proxy address should be unblock.oxylabs.io and the port 60000. It also requires the “ignore SSL certificate” flag to work properly, which is --ignore or the short form -k. Lastly, you’ll also have to pass the sub-user credentials that you’ve got in the previous step. Use the -U flag to pass user credentials. It’ll look similar to this:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" "WEBSITE_URL"

Note that you’ll have to replace the USERNAME, and PASSWORD with the appropriate credentials to make it work.

4. Send a GET request to the API

Next, you’ll have to replace WEBSITE_URL with the API url. Let’s use the ip.oxylabs.io/location API for now. You can replace it with the REST API of your preference if you want. So, the command will be:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" "https://ip.oxylabs.io/location"

If you run this command, it’ll send a GET request to the url and retrieve the response. The website https://ip.oxylabs.io/location shows the IP address of the user’s device. Web Unblocker automatically rotates proxy IP addresses for you. If everything is working properly, you should see a different IP address than that of your device’s. If you run the command again, you’ll see another IP address different from the previous one. We've delved deeper into sending GET requests with cURL on another post, so feel free to check it out.

You can also create a unique session id by passing a special header X-Oxylabs-Session-Id with your requests. This will make sure the proxy IP address remains the same for multiple network requests sent through the session id:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" -H "X-Oxylabs-Session-Id: session-1" https://ip.oxylabs.io/location

Notice the flag for setting a custom header is -H. You can also change the string session-1 to something else; it'll work as long as the string is valid and always remains the same. 

Web Unblocker has some more features such as Javascript rendering, custom cookies, headers, and geo-location. Check out the documentation to learn more.

5. Send a POST request to the API

To send a POST request using cURL, you’ll have to set a new flag --request to POST. Along with this flag, you’ll also have to pass another flag --data with the data that you want to post to the API:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" --request POST --data '{"name": "John"}' https://ip.oxylabs.io/location

As you can see, we’re passing a JSON object containing a single field named name with a value of John. If the API supports multiple fields, you can pass them all together in a single JSON object. For example:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" --request POST --data '{"name": "John Doe", "email": "jd@example.com"}' https://example.com/api/post

Here, you’re passing two fields name and email.

6. Send a PUT request to the API

Similarly, you can use cURL to send a PUT request to an API. The PUT method is used for updating data. You’ll have to change the argument of the --request flag to PUT. Let’s say you want to update the email address of the previous example and replace jd@example.com with johndoe@example.com. Then, the command will become:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" --request PUT --data '{"name": "John Doe", "email": "johndoe@example.com"}' https://example.com/api/update

Once you run the above command, cURL will use a proxy to send a PUT request to the API.  After receiving the PUT request, the API will update the email address of the entry with the name John Doe.

7. Send a DELETE request to the API

cURL also supports the DELETE request of the HTTP protocol. This can be set with the flag --request DELETE.  Let’s remove the previous entry by running the following command:

curl -k -x unblock.oxylabs.io:60000 -U "USERNAME:PASSWORD" --request DELETE --data '{"name": "John Doe", "email": "johndoe@example.com"}' https://example.com/api/remove

This will remove the entry with the name John Doe.

cURL alternatives

There are multiple alternatives to cURL that offer similar functionality and capabilities. One of them is Postman, a popular API testing tool that offers a comprehensive graphical interface for testing and debugging APIs. And if you’re familiar with programming, then Python scripts can also be useful to test APIs. Alternatively, cURL can be run in Python itself by utilizing the PycURL library.

If you’re looking for a command line alternative, then you might find HTTPie and Wget helpful. They both are robust and powerful and have all the necessary features to test or interact with REST APIs.

Conclusion

Establishing a well-defined development process that includes thorough testing is crucial for maintaining the quality and reliability of microservices and REST APIs. Tools like cURL are essential for supporting this process by providing an efficient way to test various scenarios and analyze responses. These tools can significantly improve the development process, ensuring the system's reliability and quality.

By combining cURL with Web Unblocker, you can send network requests in bulk without leaving any trace of the tracking information on your device.