Tasty REST API

# REST API

Tasty's interface is basically a REST interface. There are some slight variations from the canonical approach but they're reasonable ones. The important thing is that all interaction with Tasty is via HTTP and makes use of a lot of the functionality built into HTTP (methods, URIs, Accept: headers, etc.). JSON is used as the default data format but HTML and XML can also be used.

the basic 'tag item' request looks like:

     PUT /service/<servicename>/user/<username>/item/<itemname>/tag/<tag>/

(PUT will also work although the current implementation doesn't respond with the correct status codes yet).

to get a list of what tags a user has tagged an item with:

     GET /service/<servicename>/user/<username>/item/<itemname>/

to get a list of what items a user has tagged with a given tag:

     GET /service/<servicename>/user/<username>/tag/<tag>/

to get a list of users who have tagged an item with a given tag:

     GET /service/<servicename>/item/<itemname>/tag/<tag>/

to remove a tag from an item for a specific user:

     DELETE /service/<servicename>/user/<username>/item/<itemname>/tag/<tag>/

to remove a tag from an item, for all users:

     DELETE /service/<servicename>/item/<itemname>/tag/<tag>/

etc.

/service/<servicename>/ MUST always be the root of the request, but the other components MAY be in any order (while keeping the type/name pairs together). eg, the following requests are all equivalent and legal:

     GET /service/<servicename>/user/<username>/item/<itemname>/tag/<tag>/
     GET /service/<servicename>/item/<itemname>/user/<username>/tag/<tag>/
     GET /service/<servicename>/tag/<tag>/user/<username>/item/<itemname>/

but

     GET /user/<username>/item/<itemname>/tag/<tag>/service/<servicename>/

would be illegal.

<servicename>, <itemname>, <username>, and <tag> all MUST be URI encoded strings. everything else is pretty much legal though. spaces, non-ascii (UTF-8 is preferred), etc. are all ok. whitespace at the beginning or end will be automatically trimmed off.

lists of results will be returned in JSON format strings. if an Accept header of 'application/xml' is sent, results will instead be returned in XML.

to get a list of items that a user has tagged with more than one tag (ie, the intersection):

     GET /service/<servicename>/user/<username>/tag/<tag1>/tag/<tag2>/tag/<tag3>/

similarly, any of the above GET, POST, or DELETE requests should support specifying multiple tags, items, and/or users. multiple services are NOT supported.

## Tag Clouds

     GET /service/<servicename>/user/<username>/cloud

it will return a dictionary with 'items' and 'tags' keys, each corresponding to a list of items or tags, each with a 'count' of how many times they appear for that user.

you can actually append 'cloud' to the end of just about any of those other requests above and it will return something reasonable.

## related

> GET /service/<servicename>/item/<itemname>/related

will return a list of items that appear to be related (based on their tags + users)

also may need to specify a threshold or limit, etc.