curl

How to test a REST api from command line with curl

If you want to quickly test your REST api from the command line, you can use curl. In this post I will present how to execute GET, POST, PUT, HEAD, DELETE HTTP Requests against a REST API. For the purpose of this blog post I will be using the REST api developed in my post Tutorial – REST API design and implementation in Java with Jersey and Spring

1. Introduction

If in the first part of the blog post I will do a brief introduction to curl and what it can do (HTTP requests with options), in the second part I will “translate” the SOAPui test suite developed for the REST API tutorial to curl requests.

1.1. What is curl?

Well, curl is a command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. curl supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, HTTP/2, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, Kerberos…), file transfer resume, proxy tunneling and more.[1]

As mentioned, I will be using curl to simulate HEAD, GET, POST, PUT and DELETE request calls to the REST API.

1.2. HEAD requests

If you want to check if a resource is serviceable, what kind of headers it provides and other useful meta-information written in response headers, without having to transport the entire content, you can make a HEAD request.  Let’s say I want to see what I would GET when requesting a Podcast resource. I would issue the following HEAD request with curl:

Request

OR

Curl options 

  • -i, --include – include protocol headers in the output (H/F)
  • -X, --request – specify request  COMMAND (GET, PUT, DELETE…)  to use

Response

Note the following headers

  • Access-Control-Allow-Headers: Content-Type
  • Access-Control-Allow-Methods: GET, POST, DELETE, PUT
    and
  • Access-Control-Allow-Origin: *

in the response.

They’ve been added to support Cross-Origing Resource Sharing (CORS). You can find more about that in my post How to add CORS support on the server side in Java with Jersey.

What I find a little bit intriguing is the response header Content-Type: application/xml, because I would have expected it to be application/json, since in the resource method defined with Jersey this should have taken precedence:

1.3. GET request

Executing curl with no parameters on a URL (resource) will execute a GET.

Request

Response

Note that as expected from the HEAD request we get an xml document. Anyway we can force a JSON response by adding a header line to our curl request, setting the Accept HTTP header to application/json:

Curl options 

  • -H, --header – customer header to pass to the server

Response

If you want to have it displayed prettier, you can use the following command, provided you have Python installed on your machine.

Request

Response

1.4. Curl request with multiple headers

As you’ve found out in my latest post, How to compress responses in Java REST API with GZip and Jersey, all the responses provided by the REST api are being compressed with GZip. This happens only if the client “suggests” that it accepts such encoding, by setting the following header Accept-encoding:gzip.

Request

Curl options 

  • -v, --verbose – make the operation more talkative

To achieve that you need to simply add another -H option with the corresponding value. Of course in this case you would get some unreadable characters in the content, if you do not redirect the response to a file:

2. SOAPui test suite translated to curl requests

As mentioned, in this second part I will map to curl requests the SOAPui test suite presented here.

2.1. Create podcast(s) resource

2.1.1. Delete all podcasts (preparation step)

Request

Response

2.1.2. POST new podcast without feed – 400 (BAD_REQUEST)

Request

Response

2.1.3. POST new podcast correctly – 201 (CREATED)

Request

Response

2.1.4. POST same podcast as before to receive – 409 (CONFLICT)

Request

Response

2.1.5. PUT new podcast at location – 201 (CREATED)

Request

Response

2.2. Read podcast resource

2.2.1. GET new inserted podcast – 200 (OK)

Request

Response

2.2.2. GET podcasts sorted by insertion date DESC – 200 (OK)

Request

Response

2.3. Update podcast resource

2.3.1. PUT not “complete” podcast for FULL update – 400 (BAD_REQUEST)

Request

Response

2.3.2. PUT podcast for FULL update – 200 (OK)

Request

Response

2.3.3. POST (partial update) for not existent podcast – 404 (NOT_FOUND)

Request

Response

2.3.4. POST (partial update) podcast – 200 (OK)

Request

Response

2.4. DELETE resource

2.4.1. DELETE second inserted podcast – 204 (NO_CONTENT)

Request

Response

2.4.2. GET deleted podcast – 404 (NOT_FOUND)

Request

Response

2.5. Bonus operations

2.5.1. Add podcast from application form urlencoded

Request

Response

Note:
I am still at the beginning of using curl, so please if you have any suggestions leave a comment. Thank you.

If you liked this article, we would really appreciate a small contribution for our work! Donate now with Paypal.

Resources

Podcastpedia image

Adrian Matei

Creator of Podcastpedia.org and Codingpedia.org, computer science engineer, husband, father, curious and passionate about science, computers, software, education, economics, social equity, philosophy - but these are just outside labels and not that important, deep inside we are all just consciousness, right?

About Adrian Matei

Creator of Podcastpedia.org and Codingpedia.org, computer science engineer, husband, father, curious and passionate about science, computers, software, education, economics, social equity, philosophy.