web : What is cURL and how to use it

cURL is an incredibly powerful tool when working on the web. It can be thought of as command line alternative for postman which is used to validate the api endpoints. Imagine you are on linux box and wants to test an api’s response, quick solution is just do a curl <api end point> and done๐Ÿ™‚

-o => will save the response in a file
-i => will display response headers with actual response
-I => will display only response and no contents.
-X => is used to specifiy the verb like post, delete
-H => is sued to send the header with request
-d => is used to send post request data

Example : Most often used to validate rest api by checking the response code as 200

โžœย  restfulApis git:(master) โœ— curl -X GET http://www.google.com -I

HTTP/1.1 200 OK

Date: Sun, 20 Mar 2016 17:30:05 GMT

Expires: -1

Cache-Control: private, max-age=0

Content-Type: text/html; charset=ISO-8859-1

At its very basic, cURL makes requests to URL’s. Normally you want to interact with those URL’s in someway.

curl http://www.google.com

By default, cURL makes an HTTP GET request, so that will fetch the HTML from http://www.google.com. Awesome!

Spitting it out in the terminal isn’t so useful, so let’s save it to a file:

curl -o google.html http://www.google.com

Looking at google.html will show you the same contents as before. This is especially useful when you want to save a JSON response.

Great! Well, interacting with HTML is pretty boring, most of what I do is interacting with API’s. cURL is a great way for quickly testing your PHP script, your JSON endpoint, or what that API actually returns.

I work at CloudMine and we have a decent JSON API, so I’ll use that just as an example. Just keep in mind that the URL isn’t important here, but rather the curl options.

By default, curl makes GET requests, so let’s GET some data!

curl https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/text?keys=all  

Woh! What?

{"errors":["API Key invalid"]}

Oh, CloudMine expects an API Key to be sent as well. As an additional header? Sure, no problem:

curl https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/text \  
-H X-CloudMine-ApiKey:e90ef1aeaadd48de93b45038ed592a06

Response:
{"success":{},"errors":{}}

Excellent! Sending the correct header worked. But the response is rather vague, I’m not sure if it worked and found no data, or it didn’t work and didn’t return an error. Let’s examine the headers on the reply:

curl https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/text \  
-H X-CloudMine-ApiKey:e90ef1aeaadd48de93b45038ed592a06 -i

Response:

HTTP/1.1 200 OK  
Date: Sat, 20 Dec 2014 17:31:10 GMT  
Content-Type: application/json; charset=utf-8  
Transfer-Encoding: chunked  
Status: 200 OK  
X-Request-Id: a9fbdaec-3b3c-4b11-92d8-5af2e9f01e8e  
Cache-Control: max-age=0, private, must-revalidate  
X-Runtime: 0.020247  
X-Rack-Cache: miss  
Access-Control-Allow-Origin: *  
Access-Control-Expose-Headers: X-Request-Id

{"success":{},"errors":{}}

Adding ‘-i’ will return all the headers on the response. If you only want the headers, you can use ‘-I’.

Excellent. But the URL I want to hit is actually an endpoint for consuming data. I want to send information. Let’s make a POST request!

curl -X POST https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/text \  
-H X-CloudMine-ApiKey:e90ef1aeaadd48de93b45038ed592a06 -i
{"errors":[{"code":400,"message":"Invalid payload"}]}

Oops, we forgot to send data. To send inforamtion, we use -d.

curl -X POST https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/text \  
-d '{"myrandomkey":{"name":"ethan"}}' \
-H X-CloudMine-ApiKey:e90ef1aeaadd48de93b45038ed592a06 \
-H "content-type:application/json"

Response:

{"success":{"myrandomkey":"created"},"errors":{}}

CloudMine expects the Content-Type to be explicitely stated, so we add that as a header too. Other common ones are application/xml and application/x-www-form-urlencoded

Cool. Well, I don’t like that object, so let’s delete it.

curl -X DELETE "https://api.cloudmine.me/v1/app/928a78ffd73e4ff78383d1d4c06dd5a7/data?keys=myrandomkey" \  
-H X-CloudMine-ApiKey:e90ef1aeaadd48de93b45038ed592a06

Response:

{"success":{"myrandomkey":"deleted"},"errors":{}}

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s