API Documentation

This document describes the proposed stateless HTTP/JSON interface for accessing Zeitgeist, it can be used using any technology that supports HTTP and JSON.

You need to make sure to request with either the X-Requested-With: XMLHttpRequest or the Accept: application/json headers, requests without them are undocumented.

Error Handling

Response status codes other then 200 are error messages. They should contain a JSON body describing the Exception that occurred. You can deserialize it and throw your own exceptions (if you use a language that support exceptions).

Base Error Object

All exceptions and errors that can occur are generalized into this exception if there is no specialized error defined.

Example:

{
  "type":"RuntimeError",
  "message":"no item found with id 42"
}

Properties:

• type (String) The exception class raised.
• message (String) Message describing what happened.

DuplicateError Object extends Exception Object

Properties:

• id (Integer) The item that looks like the duplicate.

CreateItemError Object extends Exception Object

If an error occured during the creating of the item, processing will be stopped and this exception raised including all items that had successfully been created.

Properties:

• error (Exception Object) The error that occured and stopped the process.
• items (Array of Item Objects)

RemoteError Object extends Exception Object

Properties:

• error (Exception Object)
• url (String)

Authentication

User authentication is optional but required for some tasks like removing images and upvoting. Each documented request describes the level of authentication required (Guest/User/Admin Access).

Third-party applications may allow user authentication using this simple shared secret that provides a stateless authentication method.

GET /api_secret

Parameters: redirect (optional)
Returns: {email: eMail, api_secret: Secret Key}
Access: User
Description: The site generates (if not already generated) and stores a secret API key that is shown to the user. An optional redirect argument may be used to manually redirect the user back to the third-party application with the api secret appended. In any case the user tells the third-party application their api secret that is generated and shown on this page. Each user has a single unique shared api secret, he can later revoke all access from third-party applications by regenerating a new key.
A third-party application can request this with an X-API-Auth header and verify the validity of the key.

All Requests

Header: X-API-Auth
Value: User eMail + "|" + API Secret
Example: user@example.com|b613679a0814d9ec772f95d778c35fc5ff1697c
Description: Any request can authenticate a user with their shared secret.

Items

Item Object

Example:

{
  "id":18598,
  "type":"image",
  "image":{
    "image":"/asset/201202/zg.n0cb.jpeg",
    "thumbnail":"/asset/201202/zg.n0cb_200.jpeg"
  },
  "source":"test.jpg",
  "title":null,
  "created_at":"2012-02-04T08:55:39+01:00",
  "nsfw":false,
  "size":5718,
  "mimetype":"image/jpeg",
  "checksum":"374701c5db969fb3777be540180dbd14",
  "dimensions":"175x178",
  "upvote_count":0,
  "tags":[{
    "id":174,
    "tagname":"test"
    "count":1
  }]
}

Properties:

• id (Integer) Serial number uniquely identifying an item
• type (String) The type of this item, currently image, audio and video are supported. Currently only images can be uploaded by file, remote uploads (by URL) support a few video and audio services like Youtube, Vimeo and Soundcloud.
• image (Object) Contains image (String) and thumbnail (String) absolute web path (based on the URL of the API) or an absolute URL (starting with http://, this is planned for non-local storage)
• source (String) May contain the original filename of the upload, or the source URL (remote_url)
• title (String) The title of this item that may have been parsed by a remote url. Like the title of a YouTube video etc.
• created_at (String) The date/time this item was created. It is planned to create a updated/recreated future property that is set if this item is submitted again (see issue #21)
• nsfw (Boolean) Indicate if this item is tagged with the nsfw tag.
• size (Integer) The size of the image in bytes.
• mimetype (String) Mimetype of the item. (image/jpeg, image/png, image/gif)
• checksum (String) MD5 hexdigest of the image.
• dimensions (String) The width and height of the image.
• upvote_count (Integer) The number of upvotes for this item.
• tags (Array Of Tag Objects) The tags associated with this item.

Tag Object

Example:

{
  "id":174,
  "tagname":"test"
  "count":1
}

Properties:

• id (Integer) Serial number uniquely identifying an tag
• tagname (String) Tag name (case insensitive), also uniquely identifying
• count (Integer) Number of items that are assigned with this tag. (number of 'taggings')

POST /new

Parameters:

• image_upload[] (File Upload) One or more uploaded image files.
• remote_url[] (String) One or more absolute URLs for remote uploading. This supports direct links to images, aswell as links to supported services like Imgur, ImageShack, YouTube etc.
• tags (String) List of comma separated tags that are assigned to the item after creation.
• announce (Boolean) If this new item should be announced in IRC or not.
• ignore_fingerprint (Boolean) Ignores the fingerprint of the item, omits duplication check based on fingerprint.

Returns: {items: Array of Item Objects}
Throws: CreateItemError Object
Access: Guest
Description: This creates new media items either by uploading files or by remote URLs. It returns the newly created Item Objects along with an array of Tag Objects that have been assigned to these items. If an error occurred the processing stops, already created item objects are returned along with the error that stopped it.

GET /

Parameters:

• after (Integer) The ID of the item to start from. (exclusive)
• before (Integer) The ID of the item to end with. (exclusive)
• page (Integer) Page of result set. (25 items per page by default)

Returns: {items: Array of Item Object}
Access: Guest
Example: /?after=42&page=4
Description: Returns Item objects.

GET /:id

Parameters:

• :id (Integer) The ID of the Item Object you want to get.

Returns: {item: Item Object}
Access: Guest
Description: Returns the Item Object and associated Tags.

POST /update

Parameters:

• id (Integer) The ID of the Item Object you want to update.
• add_tags (String) Comma seperated list of tags to add.
• del_tags (String) Comma seperated list of tags to remove.

Returns: {item: Item Object}
Access: Guest
Description: Creates (if new) and assigns or removes tags from an item specified by id

POST /delete

Parameters:

• id (Integer) The ID of the Item Object you want to delete.

Returns: {id: ID of deleted Item Object}
Access: User (submitter of item) or Admin
Description: Removes an Item specified by id.

POST /upvote

Parameters:

• id (Integer) The ID of the item you want to vote for.
• remove (Boolean) True if you want to delete/undo your vote.

Returns: {id: ID of item, upvotes: current number of upvotes}
Access: User
Description: Vote for item specified by id, if remove is set to true it will undo the previous vote. This request needs to be authorized.

POST /search

Parameters:

• q (String) Partial tag to search for.

Returns: {tags: Array of Tag Objects}
Access: Guest
Description: Returns list of tags containing q.

GET /show/tag/:tag

Parameters:

• :tag (String) The name of the tag.
• after (Integer) The ID of the item to start from. (exclusive)
• before (Integer) The ID of the item to end with. (exclusive)
• page (Integer) Page of result set. (25 items per page by default)

Returns: {items: Array of Item Object}
Access: Guest
Description: Returns items that are assigned with that tag.

GET /list/tags

Returns: {tags: Array of Tag Objects}
Access: Guest
Description: Return all stored tags.