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.
To use cURL to PUT/GET files, see here.
[...] 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.
Useful breakdown of curl commands, thanks dude.
[...] For more examples using cURL for testing web services, see here. [...]
Thank you for your concise post. It helps greatly, especially the POST request.
I am not able to use the delete command of CURL
curl -v -X DELETE http://198.45.22.153/gradeguru-api/me/grades/48?access_token=“access token”
The above command says Rcv failure, connection was reset, however if I use localhost in place of the above URL, it deletes the record.
Please help!
hi,
i am looking to run a small experiment on REST services, do you know of a directory of publicly available services, or any other way of gathering as many REST service addresses as possible?
thanks!
jnahon AT gmail DOT com
James,
I’m not aware of any directory of various REST apis. But I can point you to websites that expose their application functions via REST. Google Storage is a good example. So is Netflix – http://developer.netflix.com/blog/read/Introducing_the_Netflix_API.
Is 198.45.22.153 the IP address of your local machine (localhost)?
It could be due to the connection timing out. You may want to test further to figure out this issur
i want to know how to use CURL to pass a Request body to a REST Server. when I send with -d I get an error “application/x-www-form-urlencoded” is not supported”
What REST server are you using? Check that the REST Resource you are invoking to confirm that it can accept POST methods
A few aliases for bash if you’re lazy like me
#= REST cURL tests
# rest-get http://192.168.0.165/persons/person/1
alias rest-get="curl -i -H \"Accept: application/json\""
# rest-post "firstName=james" http://192.168.0.165/persons/person
alias rest-post="curl -i -H \"Accept: application/json\" -X POST -d "
# rest-put "phone=1-800-999-9999" http://192.168.0.165/persons/person/1
alias rest-put="curl -i -H \"Accept: application/json\" -X PUT -d "
# rest-delete http://192.168.0.165/persons/person/1
alias rest-delete="curl -i -H \"Accept: application/json\" -X DELETE "
# rest-post-put "phone=1-800-999-9999" http://192.168.0.165/persons/person/1
alias rest-post-put="curl -i -H \"Accept: application/json\" -H \"X-HTTP-Method-Override: PUT\" -X POST -d "
# rest-post-delete http://192.168.0.3:8090/persons/person/1
alias rest-post-delete="curl -i -H \"Accept: application/json\" -H \"X-HTTP-Method-Override: DELETE\" -X POST "
REST Services Best Practices…
Einleitung An dieser Stelle wollen wir unsere Erfahrungen und Vorstellungen für eine saubere REST Service Architektur sammeln und dokumentieren. Dies soll Wildwuchs in der Art, wie unsere Schnittstellen aussehen, eindämmen helfen…….
[...] was reading REST-esting with cURL and found this very useful for manually testing my Rails JSON APIs. I am using Cucumber for my [...]
[...] Curious » REST-esting with cURL. Common ← How to fstab – Ubuntu Forums Leave a comment ?0 Comments. [...]
[...] cURL to test findOrder Rest service. If you are new to cURL, I suggest the reading of REST-esting with cURL to get started with it. A good alternative to cURL to debug RESTful web services is a nice Firefox [...]
[...] ที่มา REST-esting with cURL [...]