REST-esting with cURL
I have been working on RESTful web applications over the past few months and have been using cURL to quickly test functionality.
The following are basic curl commands to test REST resources
POSTing data to a REST resource:
curl -i -H "Accept: application/json" -X POST -d "firstName=james" http://192.168.0.165/persons/person
where,
i – show response headers
H – pass request headers to the resource
X – pass a HTTP method name
d – pass in parameters enclosed in quotes; multiple parameters are separated by ‘&’
The above command posts the first name “james” to the persons resource. Assuming the server creates a new person resource with first name of James, I also tell the server to return a json representation of the newly created resource.
PUT a resource:
curl -i -H "Accept: application/json" -X PUT -d "phone=1-800-999-9999" http://192.168.0.165/persons/person/1
This puts a phone number to the person resource created in the previous example.
GET a resource:
curl -i -H "Accept: application/json" http://192.168.0.165/persons/person/1
For GET requests, the -X GET option is optional.
curl -i -H "Accept: application/json" http://192.168.0.165/persons?zipcode=93031
You can pass in query parameters by appending it to the url.
curl -i -H "Accept: application/json" "http://192.168.0.165/persons?firstName=james&lastName=wallis"
The resource uri needs to be quoted if you pass in multiple query parameters separated by ‘&’. If you have spaces in the query values, you should encode them i.e. either use the ‘+’ symbol or %20 instead of the space.
DELETE a resource:
curl -i -H "Accept: application/json" -X DELETE http://192.168.0.165/persons/person/1
To delete a resource, supply DELETE as a -X option.
Using POST to PUT a resource:
curl -i -H "Accept: application/json" -H "X-HTTP-Method-Override: PUT" -X POST -d "phone=1-800-999-9999" http://192.168.0.165/persons/person/1
Some clients do not support PUT or it’s difficult to send in a PUT request. For these cases, you could POST the request with a request header of X-HTTP-Method-Override set to PUT. What this tells the server is that the intended request is a PUT.
Most web servers (or you could code it) support the X-HTTP-Method-Override and convert the request method to the intended HTTP method (value of the X-HTTP-Method-Override)
This example puts a phone number (by POSTing) to the person resource identified by 1.
Using POST to DELETE a resource:
curl -i -H "Accept: application/json" -H "X-HTTP-Method-Override: DELETE" -X POST http://192.168.0.3:8090/persons/person/1
Similar to the previous command, this example deletes the person resource identified by the above uri using the POST HTTP method but telling the server to override it with DELETE.
Another good tool to test REST resources is the Poster Firefox Add-on. It’s a great GUI tool if you do not want to get down and dirty with cURL or if you are testing from Windows (of course you could install Cygwin and then install and use cURL).
But I’m still more productive with cURL as opposed to Poster.
[...] We can use curl to make a rest request (http://blogs.plexibus.com/2009/01/15/rest-esting-with-curl/) [...]
I’ve been trying to use cURL to access a URL-shortening API like TinyURL, bit.ly, or tr.im. My problem for all three of these is that I need to pass it a long URL that contains multiple parameters itself, e.g.,
curl -d “url=http://www.prh.noaa.gov/ptwc/?region=1&id=pacific.2009.04.18.193652″ http://tinyurl.com/api-create.php
curl -d “url=http://www.prh.noaa.gov/ptwc/?region=1&id=pacific.2009.04.18.193652″ http://api.tr.im/api/trim_simple
The result is always the same: it truncates the long url at the & (therefore only using the first argument, region, instead of both, region and id).
Any ideas?
Brian,
You need to encode the “&” sign since it’s part of the “url” query parameter. In this case, “%26″. You need to do this since “&” is treated as a query parameter separator.
So the example would look like:
curl -d “url=http://www.prh.noaa.gov/ptwc/?region=1%26id=pacific.2009.04.18.193652″ http://tinyurl.com/api-create.php
Output tiny url: http://tinyurl.com/c6tu9n
Another example:
$ curl -d “url=http://www.prh.noaa.gov/ptwc/?region=1%26id=pacific.2009.04.18.193652″ http://api.tr.im/api/trim_simple
Output: http://tr.im/knmk
HTH,
RAS
the command curl -X POST -d saved my life! I previously couldn’t manually POST to an RPX api function (now I can). Thanks a lot!
Some json web services expect their input in multipart form-data, so instead of doing -d”user=a&pass=b” you need to do -F”user=a” -F”pass=b”.
One example is the reviewboard.org json api.