Quoth API Spec

quoth-api-spec.md

API Spec

Standard stuff

Every request should contain the following headers:

• Quoth-Client: an user-agent type string, eg. Quoth-iOS 3.2

• Quoth-Authentication: a json object, like this:

  {"user":"mongo-sha-here","login_time":1234}

• Quoth-Authentication-Token: a token authenticating the above json data

Authentication

POST /auth/login

This requests creates a Quoth usage session. It authenticates with Facebook, through OAuth. A request to login looks like this:

{
    "fb-token": "..."
}

When successful, the server will respond with:

{
    "status": 200,
    "auth": "{json}",
    "token": "..."
}

These two values must be saved by the client, and subsequently sent with every request.

Users

GET /users/:user-id/feed

This returns the feed. The user must be authenticated.

GET /users/:user-id/connections

Returns a list of any user which is connected to this user. A connection means that they are both members of the same collection.

Collections

GET /collections

Returns all collections that the authenticated user is a member of.

POST /collections

Create a new collection.

PUT /collections/:collection-id

Edit a collection. Restrictions are as follow:

• owner can change its name, and list of members any way it wants
• members can only invite new members, and remove themselves
• everybody else gets a 403

Note: an array diff method may be useful. eg.

diff([1,2,3,4], [3,4,5,6]) #=> [1,2], [5,6]

GET /collections/:collection-id/quotes

As you'd imagine... this returns the quotes in a specific collection.

Quotes

POST /quotes

Creates a quote. The quote's quoter must match the current user's id.

PUT /quotes/:quote-id

Edits a quote. Only its quoter can do this.

DELETE /quotes/:quote-id

Deletes a quote. Only the quoter can do this.

Likes

Likes are unique per-user, and have an emoji associated.

POST /quotes/:quote-id/likes/:user-id

Likes the quote, for the current user. Likes are unique, a like overwrites any previous like.

DELETE /quotes/:quote-id/likes/:user-id

Un-likes the quote.

Notifications

GET /users/:user-id/notifications

Gets the notifications for the current user.

Invitations

POST /invites/facebook

This API endpoint exposes inviting friends, via Facebook Chat. Parameters are:

{
    "fb-token": "...",
    "recipients": ["quoth_id", "quoth_id", ...],
    "message": "[optional value] Blah!"
}

The message is optional. When not specified, a default one will be chosen on the server. When not present in the message, a link to Quoth will be added to the message, by the server.

Stats

This is used by the website counter. Hopefully we can deprecate this at some point, in favor of a less ghetto analytics solution.

GET /stats

Gets stats.