Client URL (usually written as curl or cURL) is a command line tool that lets you send requests.
Many API documentations explain their APIs with curl because there are many programming languages — it would be impossible to write docs that use every language in the world.
Here’s an example from Github that uses cURL:
Installing Curl
Mac and Linux computers come with curl installed by default. You can try running curl -v in your command line and see if there is a response.
curl -v-v means --version. This flag shows the version of the installed program. If curl -v responds with a version, it means curl is already installed on your computer.
If curl is not installed, you will need to download and install it.
Sending GET requests
You can send a GET request by typing curl, followed by the endpoint.
# Sends a GET request to https://api.github.comcurl https://api.github.comIf the server returns a response, you will see the body of the response in your command line.
Adding query parameters
? and = are special characters in the command line. If you want to add query parameters, you need to prepend every ? and = with \.
# Set per_page limit to 100curl https://api.github.com/users/zellwk/repos\?per_page\=100Using other methods
You can use a -X flag (make sure it’s a capital X) to set the request method.
curl -X POST https://link-to-resourceThe flag order doesn’t matter. You can put it before or after the url.
# -X POST can go after the URLcurl https://api.github.com/user/repos -X POSTSetting request headers
You can set request headers with -H.
curl -H "header1: value1" -H "header2: value2" https://link-to-resourceViewing headers
You can use -v to see headers. Request headers are prefixed with > while response headers are prefixed with <.
curl -v -H "header1: value1" -H "header2: value2" https://link-to-resource
Sending body data
To send body data, you use -d. Curl will send your data as x-www-form-urlencoded.
# Sending 2 pieces of data via curlcurl -X POST https://link-to-resource -d message1='Hello' -d message2='World'If you need to encode a value, use --data-urlencode instead of -d.
curl -X POST https://link-to-resource --data-urlencode url=https://google.comAuthentication
You can perform Basic Authentication with the -u flag.
curl -X POST -u username:password https://link-to-resourceIf you want to Bearer Authentication, you need to set an authorization header.
Line breaks
It’s much easier to read a curl request if you break up lines with \. Make sure there are no spaces after each \ for this to work correctly.
curl -X POST https://link-to-resource \-d message1='Hello' \-d message2='World' \--data-urlencode url=https://google.comCheatsheet
Here’s a table to make the commands easier to look up.
| Flag | Purpose |
|---|---|
| -X | Sets method |
| -H | Set request header |
| -u | Basic authentication |
| -v | Verbose mode (view request headers, response headers, and body) |
| -d | Set body data |
More curl flags
The flags I taught you above should be enough for most use cases. If you want to find out more about curl, you can read its documentation.
That’s all you need to know about curl!
We’re done with the Rest API chapter now.
Next, you’re going to learn how to use Node — this is a prerequisite to building a server.
Welcome! Unfortunately, you don’t have access to this lesson. To get access, please purchase the course or enroll in Magical Dev School.
Unlock this lesson