Conquer REST using curl

Get the REST

As Representational State Transfer (REST) is gaining popularity, at least in the open source part of the softwareworld, we got more and more fond of cURL the swiss-army-knife command-line tool for transfering data using varios protocols.
Given that, we'd like to take you on a little tour on how to conquer a REST api using cURL, on the example of waldstat.
We have to admit that waldstat is not chosen by accident here, as it is a web project of us. The project was written in Ruby on Rails, which shows to be one of the best decision we have done on that project, so far. One side effect of using Ruby is the simplicity of serving different formats, esp. of serving them in a REST full way. But thats different story.

Back to our story, back to waldstat. Imagine an application not only keeping track of were you are and were you have been, but also allowing you to let your social graph know of what you are up to and were you will be.
This is what waldstat will do for you in an lightweight manner. You can explore new locations initialize new events and announce your attendance to them.

Now all these actions can be triggered on the webapplication, but they are also available by the json or xml based REST api.

But first before you can get started you need to get yourself a developer key. Also, it doesn't harm to keep an eye on the API documentation of waldstat.

1. Get yourself a developer api key

Home -> Settings -> API Key -> Get a key
Now you are all set.

2. Create Location

To create a location we submit the data in the JSON format, with a curl PUT call. Without lat and lng your current position from your client is used. The address is always automatically filled from your location. If your account is connected to twitter and facebook a status message update that you are creating a new waldstat location is posted to twitter and/or facebook.

• The -H option adds extra Headers to the request.
• The -v option makes the fetching more verbose
• The -d option sends the specified data in a POST request to the HTTP server, in the same way that a browser does when a user has filled in an HTML form and presses the submit button.

Note, if everything goes allright, the server will answer like this:


< HTTP/1.1 201 Created
< Connection: close
< Date: Fri, 10 Sep 2010 14:58:49 GMT
< Location: http://api.waldstat.com/locations/39


The '201 Created' indicates that indeed a location was created and that this location may be received using the value given in the 'Location' header field. Go ahead and try it:

3. Create an Event

Now that an location was created you can create an Event using a similar curl call with the event name, the location id, the date an an optional description.

Also here the server should answer with an HTTP state and a location for the newly created event.

4. Will attend

An location was created also an event, now someone needs to attend it.
Will attend requires a simple GET with the event id. In our example the eventid is 41.

5. Checkin

Checkin is a shortcut for creating an new event and attending it instantly.
To do this for the location with the id 42 use /locations/42/checkin.
Now the personal event for you is created on the location and you are logged right into it.
Note: your twitter and facebook friends are informed.

This ought to be the end ouf our little tour. We hope that you understand our appreciation for the cURL tool.
Also we wouldn't mind feedback on your experiences on our little webapplication project.

Keep an eye on the waldstat API Documenation http://groups.google.com/group/waldstat-api/web/api-documentation

Bear with us, as it is still a project in pgrogress...

And last but not least we should not forget to thank your friends of united-coders that kindly gave us the opportunity to publish this post on their site.

Thank you for your attention.