You know, curl is a free and open source command line tool and library for transferring data with URLs. It is widely-used by developers for quickly testing REST APIs in command line. In this article, I’d like to share with you how to test REST APIs using curl. In other words, you will learn how to use curl’s options for testing CRUD APIs (Create, Retrieve, Update and Delete).

NOTE: curl is installed by default on major operating systems (Mac, Windows, Linux, Unix). If your OS doesn’t come with pre-installed curl, you can download and install curl from its homepage.

The basic syntax of curl command is:

curl [options…] <url>

To see a list of options by categories, type curl --help. To see all options, type curl --help all.

Note that curl’s options are case-sensitive, e.g. -i and -I are different.

Table of content:

1. Use curl to Test Retrieval REST APIs

2. See Details of Request and Response

3. Use curl to Test Create REST APIs

4. Use curl to Test Full Update REST APIs

5. Use curl to Test Partial Update REST APIs

6. Use curl to Test Delete REST APIs

 

1. Use curl to Test Retrieval REST APIs

REST APIs of read operation handle HTTP GET requests, so just type curl <url> to test retrieval REST API. For example:

curl https://api.github.com/octocat

If testing on localhost, you can omit the http prefix, like this:

curl localhost:8080/api/students

A sample response would look like the following:

[{"id":1,"name":"Nam Ha Minh"},{"id":2,"name":"Alex Stevenson"},{"id":3,"name":"Ravi Kumar"}]

Typically, the response of a REST API is a JSON document. If you want to format the JSON to make it more readable, pipe the curl command with jq (on Windows) or json_pp (on Mac, Linux). For example:

curl localhost:8080/api/students | jq

You will see the JSON data is prettified. For example:

The above command is equivalent to the following:

curl -X GET localhost:8080/api/students | jq

You can use the -X flag to specify HTTP method of the request. Since curl uses GET by default, you don’t have to specify it explicitly.

Read this article to know how to format JSON with curl. Note that the pipe syntax won’t work with some curl’s options.

2. See Details of Request and Response

You can use the -i option to include the status code and headers in the output. For example:

curl -i localhost:8080/api/students

this gives the following output:

You can see the status code is 200 and 3 headers: Content-Type, Transfer-Encoding and Date.

And use the -v flag to see verbose output that prints the details of both request and response. The following command:

curl -v localhost:8080/api/students

will give the following output:

Here, in the verbose output, you can see the headers of request and response, along with other information that might be helpful in case you need to understand what was really going on. You can also specify the flags after the URL:

curl localhost:8080/api/students -v

NOTE: type curl --help all to see all curl’s options.

3. Use curl to Test Create REST APIs

Suppose that we want to test adding a student with the end point path /api/students and only name of the student needs to be specified - So use the following command:

curl -H "Content-Type: application/json" -d "{\"name\": \"John Doe\"}" localhost:8080/api/students

Here, we use the -H flag to specify a request header with name Content-Type and value application/json - that tells the server that the content type of the request is JSON.

And use the -d flag to specify the HTTP POST data in the request’s payload. In the above command, it is a JSON document representing a student object which has only one field name:

"{\"name\": \"John Doe\"}"

For JSON document, you must enclose String values in double quotes (“”) which need to be escaped using the backlash character \.

Following is another example that calls the end point path /api/v1/products to add a new product with name and price:

curl -H "Content-Type: application/json" -d "{\"name\": \"New Product\", \"price\": 199.99}" localhost:8080/api/v1/products

If the command is too long, you can use the character ^ as line continuation (on Windows) for more readability. For example:

On MacOS and Linux, you can use the character \ as line continuation, for example:

curl -v -H “Content-Type: application/json” \
-d “{\”name\”: \”John Doe\”, \”birthDay\”: \”2001-03-25\”}” \
localhost:8080/api/v1/students

NOTE: Since we use the -d flag to specify data in the request’s body, curl understands that the request method must be POST - meaning that you don’t have to use the -X flag specify request method explicitly.

4. Use curl to Test Full Update REST APIs

Suppose that we want to test full updating a student with the end point path /api/students and we need to specify ID and name of the student, use the following command:

curl -X PUT -H "Content-Type: application/json" -d "{\"id\": 1, \"name\": \"Ha Minh Nam\"}" localhost:8080/api/students

This will replace the student ID 1 with the specified new name. Here, we specify the request method is PUT because by convention, full update REST APIs handle PUT requests.

5. Use curl to Test Partial Update REST APIs

Suppose that we want to test partial updating a product with the end point path /api/v1/products/{id} and only product price needs to be updated - So use the following command:

curl -X PATCH -H "Content-Type: application/json" -d "{\"price\": 879.99}" localhost:8080/api/v1/products/100

This will update price of the product ID 100 to 879.99 (partially update). And as you see, the request method is PATCH, which is required by partial update REST APIs by convention.

 

Spring Boot REST APIs Ultimate Course

Hands-on REST API Development with Spring Boot: Design, Implement, Document, Secure, Test, Consume RESTful APIs.

6. Use curl to Test Delete REST APIs

Suppose that we want to test deleting a student with the end point path /api/students/{id}, use the following command:

curl -v -X DELETE localhost:8080/api/students/2

Here, we specify the request method is DELETE, and -v flag to see verbose output. If the data was removed and the delete API is implemented properly, you will see the status code 204 No Content.

So you have learned how to use curl command to test REST APIs with CRUD (Create, Retrieve, Update and Delete) operations. Note that curl is much more powerful than what I have shown you in this article. To learn more, type curl --help or curl --help all to explore the full list of options.

Watch the following video to see how I use curl to test REST APIs in action:

 

Related REST API Tutorials:

• How to Use Postman for Testing REST APIs (Test CRUD Operations)
• REST API Best Practices: How to Use the Right HTTP Methods and Status Codes
• Java RESTful Web Services Tutorial for Beginner with Jersey and Tomcat
• Java CRUD RESTful Web Services Examples with Jersey and Tomcat
• Spring Boot Hello World RESTful Web Services Tutorial
• Spring Boot RESTful CRUD API Examples with MySQL database
• Spring Boot File Download and Upload REST API Examples
• Spring Boot REST API CRUD with HATEOAS Tutorial
• Spring Boot REST API Request Validation Examples

 

Recommended Course:

• Spring Boot REST APIs Ultimate Course