Our Blog

Latest news and updates from BinaryOps.io

Consuming APIs with cURL

Performing operations on any API can be done quite simply with a little scripting and cURL.

From the man-page, cURL is described as a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, TELNET and TFTP). The command is designed to work without user interaction. curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer resume, Metalink, and more.

That's all pretty amazing and I'll no doubt only scratch the surface with this tool, but what I found below is definitely worth sharing.

A cURL command can be as simple as:

$ curl https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js

The above command will use an HTTP GET request to fetch the minimized jquery script and dump it to your terminal window. While that's not especially useful in itself, it's the building block and a place to start.

I'm not one for reading minified javascript, so let's dump the output to /dev/null by adding "-o /dev/null" to our command.

$ curl https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js -o /dev/null

Specifying an output destination turns on a text interface to let us know how the transfer is progressing.

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 72174    0 72174    0     0   537k      0 --:--:-- --:--:-- --:--:--  538k

We can turn that off by adding "-s" for silent mode.

$ curl https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js -s -o /dev/null

Skipping ahead a bit, I'm going to put the URL into an environment variable so we can call it multiple times without repeating it in the command. I'm also going to define my own output template for the output. In the template I can include placeholders where curl will insert variables from the completed transfer.

$ JUNK=https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js
$ curl -s -w "tcp: %{time_connect} ssl:%{time_appconnect} pre:%{time_pretransfer} tot:%{time_total}\n" -o /dev/null $JUNK

Now we are displaying the timing for each of the steps involved in doing an SSL request & transfer.

tcp: 0.113 ssl:0.296 pre:0.296 tot:0.423

Adding a second & third "-o /dev/null" (yes, now it makes the same request 3 times!) to the above command, shows how we can shave time off our transfers by re-using the connection and only doing the SSL handshake once.

$ JUNK=https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js
$ curl -s -w "tcp: %{time_connect} ssl:%{time_appconnect} pre:%{time_pretransfer} tot:%{time_total}\n" -o /dev/null $JUNK -o /dev/null $JUNK -o /dev/null $JUNK

Here you get to see the overhead introduced by the SSL handshake, and the value of re-using an established connection.

tcp: 0.050 ssl:0.101 pre:0.101 tot:0.175  (<--Includes SSL handshake & content)
tcp: 0.000 ssl:0.000 pre:0.000 tot:0.037  (content only, because SSL has been established)
tcp: 0.000 ssl:0.000 pre:0.000 tot:0.037  (content only, because SSL has been established)

Once you master the curl command, applying that same knowledge to PHP's cURL commands, it's pretty simple to start manipulating your API with PHP. If you're hitting your BinaryOps.io API with curl on the command line or in PHP, drop us a line, I'd love to see what solutions you've come up with.

Tags :  APIs  General