API Docs

v1

General Structure

The overarching concept in the v1 API is the dataset. Each dataset is owned by a particular user. The URL to a dataset resource is structured as follows:

http://api.shareabouts.org/api/v1/<username>/datasets/<dataset>/

Sometimes this will be referred to as the dataset root -- the base URL from which URLs to all content in a dataset can be derived. The resource at this URL contains identifying information about the dataset, as well as summary metadata about the contents. The structure of the resource (represented as JSON) is as follows:

{
  "display_name": "The Dataset's Name",
  "slug": "dataset-slug",
  "url": "http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/",
  "id": 123,

  "owner": {
    "username": "owner-name",
    "id": 12
  },
  "places": {
    "url": "http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/places/",
    "length": 278
  },
  "submissions": [
    {
      "type": "comments",
      "url": "http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/comments/",
      "length": 40 
    },
    {
      "type": "support",
      "url": "http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/support/",
      "length": 40 
    }
  ],
  "keys": {
    "url": "http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/keys/"
  },

  "created_datetime": "2012-02-24T12:46:00.000",
  "updated_datetime": "2012-02-24T12:46:00.000"
}

The parts of a dataset

• display_name -- A human-readable name describing the dataset
• slug -- An identifier for the dataset, using only characters that are valid in a URL, unique to the owner
• id -- The numerical identifier assigned to the dataset by the underlying storage system
• owner -- A summary of the user that owns the dataset
• places -- A reference to the dataset's places, along with a count of how many there are
• submissions -- A list of references to the dataset's submission sets, along with their lengths (a dataset's complete set of submissions across all submission sets can be retrieved at http://api.shareabouts.org/api/v1/owner-name/datasets/dataset-slug/submissions/)
• keys -- A reference to a list of API keys that must be used in order to write to the dataset. A dataset key should be sent in the X-Shareabouts-Key header of a request.

Everything in a dataset can be publicly read, except for the keys. In order to access the list of dataset keys, you must be authenticated by the API as the dataset owner (by username and password or some other means).

Creating a dataset

In order to create a dataset through the API, a user must be authenticated by username and password, or by some other direct means, not by an API key.

POST to http://api.shareabouts.org/api/v1/owner-name/datasets/

• Login required
• data: { "display_name": "My New Dataset", "slug": "my-dataset" }

The slug must be unique among the owner's datasets. On success, a 201 response will be returned with the full content of the dataset, as above.

Updating a dataset

PUT to http://api.shareabouts.org/api/v1/owner-name/datasets/my-dataset/

• Login required
• data: { "display_name": "My Updated Dataset", "slug": "my-dataset" }

Only these attributes may be modified directly through the API. All of the other dataset attributes are calculated (like "url"), or updated automatically (like "updated_datetime"). Send all modifiable fields when updating a dataset.

Replies with 200 on success.

Destroying a dataset

• Login required

Replies with 204 on success.

Places

Submissions

Your submission sets may be named anything, but you should avoid the following names:

• places
• submissions
• keys
• activity

These should be treated as reserved words. The submission set name gets appended to the dataset or place root in order to get those submissions for the given dataset or place. Using these names will result in a collision, and may result in an error code.

Notes for v2

dataset.submissions and place.submissions should be dataset/place.submission_sets. Within a submission set, type should be renamed to name (it's the name of the submission set). submission.type should be renamed to submission.set_name