REST

Basics – REST

RESTful Resources

The GeoComons API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method.

GeoComons presently supports the following data formats: XML, JSON, and the RSS and Atom syndication formats.

See Microformats REST URLs documentation for more information.

HTTP Requests

Methods to retrieve data from the GeoCommons API require a GET request. Methods that submit, change, or destroy data require a POST. A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method.

HTTP Headers

Where noted, some API methods will return different results based on HTTP headers sent by the client. For example, most methods that allow a since parameter will also respond to an If-Modified-Since header. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.

HTTP Status Codes

The GeoCommons API attempts to return appropriate HTTP status codes for every request. Here’s what’s going on with our various status codes:

• 200 OK : everything worked as expected.
• 304 Not Modified : there was no new data to return.
• 400 Bad Request : your request is invalid, and we’ll return an error message that tells you why.
• 401 Not Authorized : either you need to provide authentication credentials, or the credentials provided aren’t valid.
• 403 Forbidden : we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
• 404 Not Found : either you’re requesting an invalid URI or the resource in question doesn’t exist (ex* : no such user).
• 500 Internal Server Error : we did something wrong. Please let our support team know.
• 502 Bad Gateway : returned if GeoCommons server is down or being upgraded.
• 503 Service Unavailable : the GeoCommons server is up, but is overloaded with requests. Try again later.

Authentication

Some GeoCommons API methods require authentication. These are generally for any method that will add, modify, or delete resources from the system such as uploading a dataset, creating a map, or adding metadata. Methods that only get or view data do not require authentication such as downloading data or getting a map image.

Currently GeoCommons uses HTTP Basic Authentication or Session cookies.

Session Authentication

To create a new session, you must POST to the /sessions with your Geocommons login and password

curl -d "login=yourusername" -d "password=yourpassword" -X POST http://finder.yourgeocommons.local/sessions

The session cookie will then be in the ‘set-cookie’ HTTP Header parameter and can be used in the ‘cookie’ header for successive API calls.

HTTP Basic Authentication

Basic Auth requires sending the username and password on every request:

curl -u "yourusername:yourpassword" -d "overlay[wild_url]=http://earthquake.usgs.gov/eqcenter/catalogs/1day-M2.5.xml" http://finder.yourgeocommons.local/overlays.xml