cURL is a powerful command line tool for working with the web, but with just a few key features it’s awesome for working with your API giving you textual clarity about what’s really happening.
You could get a Firefox plugin, but that is bad because (a) you’d be using Firefox, (b) the plugins are a bit wimpy, and (c) CLI has three letters like API, and IPA, so it’s got to be better? Right?
If you’re enlightened and using a Mac, then you don’t have to do any installation work because cURL is already installed. If you are using some other OS that I am 78% through wiping from my memory, you might need to Google, download, compile, install or something. Urgh.
Check if you have cURL by opening a CLI:
19:25:48 ~ $ curl --version curl 7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5 Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtsp smtp smtps telnet tftp Features: AsynchDNS GSS-Negotiate IPv6 Largefile NTLM SSL libz 19:25:51 ~ $
Before we launch into some examples, here’s all you need to know about cURL command line options. Use –help if you are insufferably nosey.
-X METHOD Specify the HTTP method to request(advanced)
-i Include protocol headers in the output.
-d HTTP Payload data, followed by a string with your xml or json payload. Used with POST/PUT
-H HEADER Specify an HTTP header in the request, such as an API Version or API key
-D Dump HTTP response headers to stdout and storing headers to be reused, like cookies
Now for examples, and lets do them in the CRUD order!
CREATE
You use the HTTP POST verb to create new content via a REST API. In cURL language that simply means using the -X POST and -d ‘<post data>’ switches.
19:44:35 ~ $ curl -X POST -i -d '{ "id": "666", "name" : "Jeramiah" }' http://localhost:4567/api/team/666
HTTP/1.1 201 Created
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Type: text/html;charset=utf-8
X-Api-Header: 2012-07-10
Content-Length: 542
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
Date: Wed, 11 Jul 2012 18:44:37 GMT
Connection: Keep-Alive
--- HTML body snippet removed for clarity ---
Team API Version X-Api-Header - 2012-07-10
Request Method - POST
URL - http://localhost:4567/api/team/666
Accept - ["*/*"]
Body - #
Query String -
Content Length - 36
Media Type - application/x-www-form-urlencoded
HEADER -
User Agent - curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
GET
The most simple is just to get a URI. GET is the default method/verb so we don’t need to use the option, but I always include -i by muscle memory because I’m always nosey about the HTTP Response Headers when working with APIs.
19:36:52 ~ $ curl -i http://localhost:4567/api/team/666
HTTP/1.1 200 OK
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Type: text/html;charset=utf-8
X-Api-Header: 2012-07-10
Content-Length: 1248
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
Date: Wed, 11 Jul 2012 18:37:27 GMT
Connection: Keep-Alive
--- HTML body snippet removed for clarity ---
Team API Version X-Api-Header - 2012-07-10
Request Method - GET
URL - http://localhost:4567/api/team/666
Accept - ["*/*"]
Body - #
Query String -
Content Length -
Media Type -
HEADER -
User Agent - curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
UPDATE
The HTTP verb PUT is used to update existing resources in a REST API, the payload (in the -d switch).
19:50:45 ~ $ curl -X PUT -i -d '{ "id": "666", "name" : "Satan" }' http://localhost:4567/api/team/666
HTTP/1.1 202 Accepted
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Type: text/html;charset=utf-8
X-Api-Header: 2012-07-10
Content-Length: 555
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
Date: Wed, 11 Jul 2012 18:50:47 GMT
Connection: Keep-Alive
--- HTML body snippet removed for clarity ---
Team API Version X-Api-Header - 2012-07-10
Request Method - PUT
URL - http://localhost:4567/api/team/666
Accept - ["*/*"]
Body - #
Query String -
Content Length - 33
Media Type - application/x-www-form-urlencoded
HEADER -
User Agent - curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5
DELETE
Just use the -X DELETE switch and that’s it. No payload for this guy.
19:53:32 ~ $ curl -X DELETE -i http://localhost:4567/api/team/666
HTTP/1.1 202 Accepted
X-Frame-Options: sameorigin
X-Xss-Protection: 1; mode=block
Content-Type: text/html;charset=utf-8
X-Api-Header: 2012-07-10
Content-Length: 524
Server: WEBrick/1.3.1 (Ruby/1.9.3/2012-04-20)
Date: Wed, 11 Jul 2012 18:53:33 GMT
Connection: Keep-Alive
--- HTML body snippet removed for clarity ---
Team API Version X-Api-Header - 2012-07-10
Request Method - DELETE
URL - http://localhost:4567/api/team/666
Accept - ["*/*"]
Body - #
Query String -
Content Length -
Media Type
HEADER -
User Agent - curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5