How to use curl to test a REST API (original) (raw)

Table of contents

Introduction

This guide is intended to teach you the basics of interacting with a REST API using curl. As you follow these instructions, keep in mind that your computer’s files and folders likely will be different from the samples. If you already have a lot of experience with terminal on macOS, check out the commands on the homepage for quick reference material.

Prerequisites

In order follow this guide, you will need:

Let’s start with GET!

Start by opening your terminal.

curl is a “command-line tool for transferring data specified with URL syntax”, which makes it very useful for interacting with REST APIs and other web resources. It has thousands of uses, but we are going to review just a few in this guide.

Let us say you have a REST API that you want to interact with. For example, https://jsonplaceholder.typicode.com/todos/1 returns JSON data that is similar to this:

{
    "userId": 1,
    "id": 1,
    "title": "delectus aut autem",
    "completed": false
}

While we can open this example URL in our web browser, many REST APIs will not let us do that. Let’s try using curl instead.

In your terminal window, type curl https://jsonplaceholder.typicode.com/todos/1 and press Enter. You should experience a result similar to this:

This browser does not support the video element.

Demo of basic curl command

Without any options, curl defaults to interacting with the server using a GET HTTP request method, which is generally used for reading data only. We will cover the other HTTP request methods later in this guide.

Let’s add the -o option to save the output as a file instead of showing it directly in the terminal window. Type curl -o test.json https://jsonplaceholder.typicode.com/todos/1 and press Enter:

This browser does not support the video element.

Demo of basic curl command with file output

If we want, we can examine more detailed information about this interaction over the network. To do this, you can add the -v option to any curl command. Type curl -v https://jsonplaceholder.typicode.com/todos/1 and press Enter:

This browser does not support the video element.

Demo of basic curl command with verbose output

Using different HTTP request methods with curl

Now that we know how to do a basic query of a REST API using curl, we can try different HTTP methods. You can read a lot more about the different HTTP request methods on Wikipedia.

POST

The POST HTTP request method is very frequently used to create or update data on the server when interacting with a REST API. In order to do that, you will need to know a couple new options for the curl command:

Let’s put these options together into a complete command:

curl -X POST -H 'Content-Type: application/json' -d '{"title": "foo","body": "bar","userId": 123}' https://jsonplaceholder.typicode.com/posts

You can type or copy that into your terminal window and press Enter to send it, like this:

This browser does not support the video element.

Demo of POST curl command

As you can tell, that was a lot of data to try to put in a single command. We can send data using a file instead to make it easier and repeatable.

Create a new file called data.json with the following data:

{
    "title": "foo",
    "body": "bar",
    "userId": 123
}

If you have created it successfully, you should be able to cat the file, like this:

This browser does not support the video element.

Demo of data file

Now you can use that file as part of your curl command. Instead of putting the data in the command, you can refer to the file by using -d @[FILENAME]. We can try it by typing curl -X POST -H 'Content-Type: application/json' -d @data.json https://jsonplaceholder.typicode.com/posts and pressing Enter:

This browser does not support the video element.

Demo of POST curl command with a file

PUT

The PUT HTTP request method is often used to update existing data on the server when interacting with a REST API. Similar to example with POST, we want to set the method, data format, and data when using the curl command.

Let’s try updating an existing item. Type curl -X PUT -H 'Content-Type: application/json' -d '{"title": "foo_updated","body": "bar_updated","userId": 123}' https://jsonplaceholder.typicode.com/posts/1 and press Enter, like this:

This browser does not support the video element.

Demo of PUT curl command

You can also use a data file the same way you did with the POST HTTP request method, by using -d @[FILENAME].

DELETE

If you want to remove data from the server, you will likely use the DELETE HTTP request method when interacting with a REST API. This is a bit more plain compared to the previous examples. You will use -X DELETE to specify the DELETE HTTP request method and specify a specific resource URL to delete. Try it by typing curl -X DELETE https://jsonplaceholder.typicode.com/posts/1 and pressing Enter:

This browser does not support the video element.

Demo of DELETE curl command

You will notice that many REST APIs return either the deleted data or no data when using the DELETE HTTP request method.

OPTIONS

Sometimes, we need to know what types of requests or data we can send to a server. To do this, you can use the OPTIONS HTTP request method.

You will need to use the -v option that you learned earlier. This will turn on more detailed output so that you can view the “options” that the server supports.

Let’s try it by typing in curl -v -X OPTIONS https://jsonplaceholder.typicode.com/posts and pressing Enter:

This browser does not support the video element.

Demo of OPTIONS curl command with verbose output

As you scroll through your terminal window, you will observe information like this:

...
< access-control-allow-credentials: true
< access-control-allow-methods: GET,HEAD,PUT,PATCH,POST,DELETE
...

That tells you which HTTP request methods the REST API server allows. It also tells you that the server will allow you to authenticate and use credentials.

Wrapping up

Now you know a bit about using curl to interact with REST APIs and servers. This is an extremely useful command and tool.