Swiss Army knife of API testing — curl

curl is used daily by virtually every Internet-using human on the globe.

Imagine you need to send a few API calls in your CI/CD pipeline to do authentication to fetch some data, send a simple request or download a file from a web URI.

Which tools do you prefer?

The answer might be to use famous API testing tools like Postman, etc.

But believe me, you can use an ultra-lightweight, totally free tool CURL will do that for you.

So I thought, it would be worth creating an article on CURL.

I narrowed the scope of this article to HTTP/HTTPS because it will take days to write an article on the full functionalities of curl. You will find soon why I’m saying that.

What’s curl used for?

Curl, short for “Client URL,” is a command-line tool for transferring data with URLs. curl is also used in cars, television sets, routers, printers, audio equipment, mobile phones, tablets, medical devices, set-top boxes, computer games, media players etc.

Curl is the Internet transfer engine for thousands of software applications in over twenty billion installations.

Curl is used daily by virtually every Internet-using human on the globe.

Can you imagine how many protocols it supports?

DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. curl supports TLS certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies (SOCKS4, SOCKS5, HTTP and HTTPS), HTTP/2, HTTP/3, cookies, user+password authentication (Basic, Plain, Digest, CRAM-MD5, SCRAM-SHA, NTLM, Negotiate, Kerberos, Bearer tokens and AWS Sigv4), file transfer resume, proxy tunneling, HSTS, Alt-Svc, unix domain sockets, HTTP compression (gzip, brotli and zstd), etags, parallel transfers, DNS-over-HTTPS and list goes on.

Why Curl? Because it’s Easy, Everywhere, and Flexible!

1. Easy Peasy: Curl’s like the Swiss Army knife of API testing. It’s simple, straightforward, and doesn’t require a PhD in programming to use. Just type a few commands, hit Enter, and voila — you’re sending or testing APIs like a pro!
2. Available Everywhere: Whether you’re on a Mac, PC, or Linux machine, Curl’s got your back. No need to fuss over different tools for different platforms — Curl plays nice with everyone.

Let’s Get Sending API requests

First things first

Make sure you’ve got Curl installed on your computer. Don’t worry, it’s as easy as downloading an app or using a package manager. Once that’s done, you’re ready to roll!

You can download and install Curl from its official website or use package managers like Homebrew (for macOS and Linux) or Chocolatey (for Windows).

If you need more help with installation check the following article.

Install curl and libcurl

For this article, I’m using https://dummy.restapiexample.com as the demo site. So you can try out the same commands on the cmd or console.

Making Your First Request

Imagine you want to check out a list of employees from an API. Here’s how you do it with Curl:

curl https://dummy.restapiexample.com/api/v1/employees

Hit Enter, and Curl will fetch the user data for you. It’s that simple!

Output

{"status":"success","data":[{"id":1,"employee_name":"Tiger Nixon","employee_salary":320800,"employee_age":61,"profile_image":""},{"id":2,"employee_name":"Garrett Winters","employee_salary":170750,"employee_age":63,"profile_image":""},{"id":3,"employee_name":"Ashton Cox","employee_salary":86000,"employee_age":66,"profile_image":""},{"id":4,"employee_name":"Cedric Kelly","employee_salary":433060,"employee_age":22,"profile_image":""},{"id":5,"employee_name":"Airi Satou","employee_salary":162700,"employee_age":33,"profile_image":""},{"id":6,"employee_name":"Brielle Williamson","employee_salary":372000,"employee_age":61,"profile_image":""},{"id":7,"employee_name":"Herrod Chandler","employee_salary":137500,"employee_age":59,"profile_image":""},{"id":8,"employee_name":"Rhona Davidson","employee_salary":327900,"employee_age":55,"profile_image":""},{"id":9,"employee_name":"Colleen Hurst","employee_salary":205500,"employee_age":39,"profile_image":""},{"id":10,"employee_name":"Sonya Frost","employee_salary":103600,"employee_age":23,"profile_image":""},{"id":11,"employee_name":"Jena Gaines","employee_salary":90560,"employee_age":30,"profile_image":""},{"id":12,"employee_name":"Quinn Flynn","employee_salary":342000,"employee_age":22,"profile_image":""},{"id":13,"employee_name":"Charde Marshall","employee_salary":470600,"employee_age":36,"profile_image":""},{"id":14,"employee_name":"Haley Kennedy","employee_salary":313500,"employee_age":43,"profile_image":""},{"id":15,"employee_name":"Tatyana Fitzpatrick","employee_salary":385750,"employee_age":19,"profile_image":""},{"id":16,"employee_name":"Michael Silva","employee_salary":198500,"employee_age":66,"profile_image":""},{"id":17,"employee_name":"Paul Byrd","employee_salary":725000,"employee_age":64,"profile_image":""},{"id":18,"employee_name":"Gloria Little","employee_salary":237500,"employee_age":59,"profile_image":""},{"id":19,"employee_name":"Bradley Greer","employee_salary":132000,"employee_age":41,"profile_image":""},{"id":20,"employee_name":"Dai Rios","employee_salary":217500,"employee_age":35,"profile_image":""},{"id":21,"employee_name":"Jenette Caldwell","employee_salary":345000,"employee_age":30,"profile_image":""},{"id":22,"employee_name":"Yuri Berry","employee_salary":675000,"employee_age":40,"profile_image":""},{"id":23,"employee_name":"Caesar Vance","employee_salary":106450,"employee_age":21,"profile_image":""},{"id":24,"employee_name":"Doris Wilder","employee_salary":85600,"employee_age":23,"profile_image":""}],"message":"Successfully! All records has been fetched."}

CURL Options

Before we move to the examples, let’s understand some of the most useful options that you can use in CURL. Here are some commonly used options.

1. -H, — header: Allows you to include custom HTTP headers in the request. For example:

curl -H "Content-Type: application/json" https://api.example.com/resource

2. -d, — data: Sends data in the body of the request. Useful for POST and PUT requests. For example:

curl -X POST -d '{"name": "John"}' https://api.example.com/users

3. -i, — include: Includes HTTP response headers in the output. For example:

curl -o response.txt https://api.example.com/resource

4. -o, — output: Writes the response body to a file instead of printing it to stdout. For example:

curl -o response.txt https://api.example.com/resource

5. -u, — user: Provides authentication credentials (username:password) for HTTP Basic authentication. For example:

curl -u username:password https://api.example.com/resource

6. -F, — form: Sends data as a multipart/form-data request. Useful for uploading files. For example:

curl -F "file=@example.txt" https://api.example.com/upload

7. -X, — request: Specifies the HTTP request method (GET, POST, PUT, DELETE, etc.). For example:

curl -X POST https://api.example.com/resource

8. -v, — verbose: Displays detailed information about the request and response, including headers and status codes. For example:

curl -v https://api.example.com/resource

You also can combine those options. You will see more working examples below.

CURL CRUD Operations

Curl supports various HTTP methods, including GET, POST, PUT, PATCH, and DELETE, allowing you to perform CRUD (Create, Read, Update, Delete) operations on API resources. Here are examples of Curl commands for each CRUD operation:

POST (CREATE)

In the below example, “curl -X POST” indicates that the HTTP request should be a POST request. You can replace “POST” with other HTTP methods like GET, PUT, DELETE, etc., depending on the type of request you want to make.

Note:

These outputs are formatted using jq. Please check “Formatting JSON Response” section about jq , JSON processor.

curl -X POST -H "Content-Type: application/json" -d {"name":"Chamila","salary":"1000","age":"40"} https://dummy.restapiexample.com/api/v1/create

Output

{
  "status": "success",
  "data": {
    "id": 1960
  },
  "message": "Successfully! Record has been added."
}

GET (READ)

GET is the default CURL command. So you don’t need to specify any options.

curl https://dummy.restapiexample.com/api/v1/employee/1

Output

{
  "status": "success",
  "data": {
    "id": 1,
    "employee_name": "Tiger Nixon",
    "employee_salary": 320800,
    "employee_age": 61,
    "profile_image": ""
  },
  "message": "Successfully! Record has been fetched."
}

PUT (UPDATE)

curl -X PUT -H "Content-Type: application/json" -d '{"name":"Chamila A","salary":"2000","age":"40"}' https://dummy.restapiexample.com/public/api/v1/update/2

Output

{
  "status": "success",
  "data": [],
  "message": "Successfully! Record has been updated."
}

DELETE (DELETE)

curl -X DELETE https://dummy.restapiexample.com/api/v1/delete/2

Output

{
  "status": "success",
  "data": "2",
  "message": "Successfully! Record has been deleted"
}

Advanced options

Sometimes, you need to prove who you are or add special instructions to your requests. No worries — Curl’s got you covered there too!

• Adding Authentication:

curl -H "Authorization: Bearer <token>" https://api.example.com/protected/resource

• Custom Headers? Sure!:

curl -H "X-Custom-Header: Value" https://api.example.com/users

Curl is like a chameleon — it can adapt to any situation!

Curl is like a chameleon

Handling response

After sending a request, you’ll get a response back from the API. Curl can help you make sense of it all!

• Checking Response Headers:

curl -i https://dummy.restapiexample.com/api/v1/employee/1

Output

HTTP/1.1 200 OK
Date: Mon, 13 May 2024 21:58:33 GMT
Server: nginx/1.21.6
Content-Type: application/json
Cache-Control: no-cache, private
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
Cache-Control: max-age=86400
Expires: Tue, 14 May 2024 21:58:33 GMT
Vary: Accept-Encoding
X-Endurance-Cache-Level: 2
X-nginx-cache: WordPress
X-Server-Cache: true
X-Proxy-Cache: MISS
Transfer-Encoding: chunked

{"status":"success","data":{"id":1,"employee_name":"Tiger Nixon","employee_salary":320800,"employee_age":61,"profile_image":""},"message":"Successfully! Record has been fetched."}

• Saving Response Data to a file:

curl -o response.json https://dummy.restapiexample.com/api/v1/employee/1

• Formatting JSON Response:

You need to install jq for this. You can use BREW or CHOCO to install it.

In Windows

choco install jq

After the installation, you can run

curl https://dummy.restapiexample.com/api/v1/employee/1 | jq

Output

{
  "status": "success",
  "data": {
    "id": 1,
    "employee_name": "Tiger Nixon",
    "employee_salary": 320800,
    "employee_age": 61,
    "profile_image": ""
  },
  "message": "Successfully! Record has been fetched."
}

Without jq , processor output will be like

{"status":"success","data":{"id":1,"employee_name":"Tiger Nixon","employee_salary":320800,"employee_age":61,"profile_image":""},"message":"Successfully! Record has been fetched."}

Wrapping It Up

And there you have it — a crash course in API testing with Curl! Whether you’re a seasoned developer or just starting out, Curl’s your companion for all things API-related.

So next time you need to test an API, don’t sweat it — just Curl it!

Reference

everything curl

If you find the article useful consider like and subscribe.