EDDYMENS

EDDYMENS

Curl for technical writers

carbon (1)

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. OS 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. In fact, 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 -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

1

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

2

curl --location --request POST 'https://example.com' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'name=eddy' \

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 as well as 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 command for making a POST request the PATCH has the right method set -XPATCH and the respective data body to accompany it -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 by 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 pass the name as a query parameter. ie: ?name=eddy to identify the resource we will like to delete.

Uploading a file using Curl

curl POST 'https://example.com' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--form '@/Downloads/testfile.xlsx'

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.

If you found this article useful I will suggest you subscribe to my newsletter so you don't miss out on future postings :)