cURL

Last Updated Jul 03, 2021

What is cURL?

cURL is a command line tool that allows you to exchange information across nearly any point on the Web. If you've read API documentation before, you've probably seen cURL requests used to test APIs. cURL is powerful, ubiquitous, and open source, so it's a fundamental tool for your software development toolbox. There are many other API testing tools, like Postman and wget, but cURL has stayed around since the late 90s for a good reason, and if you're new to web development, it's a great way to learn to think like a web developer.

What can I do with cURL?

cURL has a bit of a learning curve, partly because it lives in the terminal and doesn't show output when you execute a command (tip: use `-v` for verbose output in cURL), partly because its documentation is a little technical. The best way to get comfortable with cURL is doing a few small operations with it first. Try these!  

Beginner cURL Operations

  • Retrieve a website, such as Abstract's: `curl https://www.abstractapi.com/`
  • Retrieve the same website, but store the output to your local machine `curl -o example.html https://www.abstractapi.com/` (Extra credit: Store the output as a JSON file: `curl -o extracredit.json http://https://www.abstractapi.com/index.html`)
  • Retrieve a website with verbose output, to see what cURL is doing behind the scenes `curl -v https://www.abstractapi.com/`

In the last example, take a close look at cURL's verbose output. We see a GET request to `https://www.abstractapi.com/`, a received 1256-byte response, and the status code `200`, which indicates our request has succeeded! If you run this request as `curl -v www.examplefail.com`, you receive a failed GET message. What does this mean?

cURL Basic API Operations

A GET operation is one of the cornerstones of REST API operations, which standardizes the HTTP communication between web services. Instead of existing on one database, as they did in the 'monolithic' era of software development, applications now exist across databases and communicate with HTTP via Application Programming Interfaces (APIs). APIs act like switchboards that authenticate and route traffic. cURL is extremely useful in quickly testing these endpoints. Here's how we perform five basic API tests in cURL, and what the operation does.

Beginner cURL API Operations

  • GET - This operation reads information from a record in the database. You might remember it as the same command we used to retrieve a website: `curl https://jsonplaceholder.typicode.com/posts`  
  • PUT- This operation changes a record’s information in the database. `curl -X PUT -d "userId=1&title=Something else&body=A new body" https://jsonplaceholder.typicode.com/posts/1`
  • POST - This operation creates a new record in the database. `curl -X POST -d "userId=5&title=Stuff and Things&body=An amazing blog post about both stuff and things." https://jsonplaceholder.typicode.com/posts`
  • PATCH - This operation updates an existing resource, but does not require sending the entire body with the request. `curl -X PATCH -d "title='Only change the title'" https://jsonplaceholder.typicode.com/posts/1`
  • DELETE - This operation removes a record from the database. `curl -X DELETE https://jsonplaceholder.typicode.com/posts/1`

We're using JSON Placeholder to test their API endpoints. Thanks for this great resource!

Conclusion

Consider the power contained in the simple operations we just performed: we sent, received, and changed data in a far away server. Imagine you're building an application and need an up-to-date geographic location: call the IP Geolocation API using cURL for an up-to-date weather report. Or maybe you need a stock report. Perhaps movie times? cURL opens the world of APIs and web development to everyone, and though its website might look old, it's here to stay. Happy travels.