setup a geospatial-restful API and document it for others

UPDATE: I’ve had some criticism of the geo_scaffold code… which was really meant for my personal use. I’m tuning it up for a public release… check back in a few weeks.

Introduction
Following on from my last post where we created a mapping app using geo_scaffold I am going to show how to use cURL to play around with the RESTful location API that geoscaffold has generated for us. Geoscaffold has built us a working RESTful API that can be used with a bit tweaking. So all resources are accessable via a URL and HTTP verbs (GET/PUT/POST/DELETE). The basic API can be accessed via KML and GeoRSS flavor of XML and can simply be access by adding “.xml”, “.kml” or “.georss” to the end of your URL.

GET

curl http://localhost:3000/hotspots/1.kml

Authentication
We can add simple HTTP authentication very easily.
You will need a username and password for accessing the API. Login/pwd can be requested. Authentication is implemented as a basic HTTP authentication. in your controller

class HotspotsController < ApplicationController
  before_filter :authenticate
  ...
  protected
  def authenticate
    authenticate_or_request_with_http_basic do |username, password|
      username == "shoaib" && password == "secret"
    end
  end
end

lets try it out:

curl -u shoaib:secret http://localhost:3000/hotspots/1.kml

WRITE
In order to write to a resource we use the POST http method.

curl -u shoaib:secret -X POST -d "hotspot[name]=Merriot-San-Francisco& \
    hotspot[description]=Where20+conference+not2b+missed&lat=37.602561& \
    lng=-122.37096" http://localhost:3000/hotspots.xml

UPDATE
Updating the database requires the PUT method.

curl -u shoaib:secret -X PUT -d "hotspot[name]=My+current+location& \
    hotspot[description]=Where20+conference+is+in+progress& \
    lat=37.602561&lng=-122.37096" http://localhost:3000/hotspots/1.xml

DELETE
Delete the database requires the DELETE method.

curl -u shoaib:secret -X DELETE http://localhost:3000/hotspots/1.xml