Curl For Technical Writers

What is Curl?

Curl is a command-line tool for making network requests to servers. It can be found on most UNIX-based systems ie: Linux and Mac OS. It can also be set up on Windows with a little bit of effort [↗].

In most of my articles I describe Postman [↗] as the go-to tool for testing out APIs, Curl also falls under this category. If you know your way around the command line, Curl is the perfect barebone alternative to Postman when it comes to API clients.

Why use curl?

As I might have hinted at in the earlier section, Curl can be used as an API client, and since it's command-line based, it opens up the ability to use it in shell scripting which can be a powerful combination when it comes to API testing. Using a tool like Postman has a bit of a learning curve, outside of knowing the parameter and filter combinations to use to make specific types of requests, you barely have to learn anything else in other to use Curl.

Another good reason to learn to use Curl as a tech writer is the fact that most developers are familiar with it and can be provided as a code example instead of examples in different programming languages. Most developers can work out the code they need from a curl example.

Making a GET request using CURL


$ curl -XGET -H 'content-type: application/json' 'https://example.com?count=10'

Above is an example of a GET request using curl. -XGET is used to denote that. A header is also set using the flag-H. in this case, the header is set for the content-type to let our server know we will be sending as well as expecting JSON as the main form of data input and output.

At the end of the command is the URL 'https://example.com?count=10' to which we are sending the request. Given that each section of the command is wrapped in quotes ' we can for example put the URL anywhere in the request.

Making a POST request using CURL


$ curl -XPOST -H 'content-type: application/json' -d '{"name":"Eddy"}' 'https://example.com'


01: curl --location --request POST 'https://example.com' \
02: 
03: --header 'Content-Type: application/x-www-form-urlencoded' \
04: 
05: --data-urlencode 'name=eddy' \
06:

Lets now look at a POST request, much hasn't changed compared to the GET request except the addition of the data body -d '{"name":"Eddy"}' in the form of JSON and the method type set to POST ie: -XPOST

The example 2 shows an example where instead of sending a JSON data body we send a form URL encoded body, which is similar to what happens when you submit a form using the HTML form tag.

A PATCH request using CURL


$ curl -XPATCH -H 'content-type: application/json'  -d '{"name":"Mike"}' 'https://example.com'

Similar to the POST request the PATCH request has the method set to -XPATCH and the respective data body to accompany it i.e: -d '{"name":"Mike"}'.

In the case of a PUT request, you will only need to change the method to -XPUT and set the right data body.

A DELETE request using CURL


$ curl -XDELETE -H 'content-type: application/json' -H "Content-type: application/json" 'https://example.com?name=eddy'

Delete requests usually do not require data bodies and so just setting the right method -XDELETEand providing the right URL to identify the resource you will like to delete is enough.

In our example, we passed the name as a query parameter. ie: ?name=eddy to identify the resource we will like to delete.

Uploading a file using Curl


01: curl POST 'https://example.com' \
02: 
03: --header 'Content-Type: application/x-www-form-urlencoded' \
04: 
05: --form '@/Downloads/testfile.xlsx'
06:

Curl also allows for file uploads, for example, the above code mimics a request similar to the one made when you upload documents using the HTML form tag. In this case, we set our content-type header to form-url encoded --header 'Content-Type: application/x-www-form-urlencoded' and then use the --form flag followed by the server expected name for the file upload then =@ followed by the absolute or complete path to the file we will like to upload. --form 'image=@/Downloads/testfile.xlsx'

You might have noticed instead of using -H for the header this time around we used --header this is the full flag name, similarly --form can be written as -F.

Conclusion

Curl is a very useful and powerful tool and we have barely scratched the surface when it comes to what you can use it for. Curl also proves to be extremely useful when used in shell scripts as this makes it possible to automate different parts of your API work.

Here is another article you might like 😊 "Diary Of Insights: A Documentation Of My Discoveries"

Tech Jobs | Newsletter [↗] 🗯️ Got a question? 🔗 Share on 𝕏