Customer: Marine Biological Laboratory / Encyclopedia of Life
A web service provider for tracking “karma” points of users who are distributed across several separate web applications.
Each resource can be accessed via HTML, JSON, or XML. To control the format, the Accept header can be set to the desired mime type, or a file extension can be appended to any URL. For example, to get the summary of bob’s karma in JSON format, you can issue a GET request to /users/bob/karma.json.
The default format is HTML.
Users in this system represent the users of the web application. They have no ability to authenticate to the Karma server. Users are uniquely identified by their URI.
Users only have one real attribute: their permalink. This is the last path segment of the URI that identifies the user. The permalink is set and chosen by the client.
Get a list of all users currently in the karma server database. Will return the same information as the /users/bob action, mentioned below, but for all users.
GET /users
Get a new user object. This method allows you to see what the user object looks like and allows you to manipulate and change it without any chance to affect any actual data.
GET /users/new
Create a new user “bob”. You will automatically be able to access the value of bob’s tags – you do not need to create the tags individually. If the user already exists, then this request will have no effect.
PUT /users/bob
Get information about user bob. This would include the creation time, bob’s karma score, latest activity, related URI’s, etc.
GET /users/bob
Rename the “bob” user to “bobby”. The resource will now only be accessible as /users/bobby (and likewise for any other place that this tag is referenced). All data associated with the user is still intact.
PUT /users/bob?permalink=bobby
Delete user “bob”, along with all of his karma and karma history.
DELETE /users/bob
Return details about bob’s total karma score. Two versions are returned – one that includes the ability for points to go negative, and the other that only allows points to go down to zero. Also included are the total positive and negative points that have been accumulated.
GET /users/bob/karma
Tags are the containers that are used to hold karma points. The client defines one or more unique tags, and these tags are then available to all users for storing points within the scope of the client’s website.
Shared Tags are tags prefixed by a ‘karma:’. An admin defines one or more unique shared tags, and these tags are then available to all users for storing points within the scope of all websites with access to the server.
Like users, tags only have one real attribute: their permalink. This is the last path segment of the URI that identifies the tag. The permalink is set and chosen by the client.
Get a list of all tags currently in the karma server database. Will return the same information as the /tags/plants action, mentioned below, but for all tags.
GET /tags
Get a new tag object. This method allows you to see what the user object looks like and allows you to manipulate and change it without any chance to affect any actual data.
GET /tags/new
Create a new tag “plants”. Each user in the system will automatically get “plants” tag. If the tag already exists, then this request will have no effect.
PUT /tags/plants
Get information about the tag “plants”.
GET /tags/plants
Change the name of the plants tag to “flowers”. The resource will now only be accessible as /tags/flowers (and likewise for any other place that this tag is referenced). All data associated with the tag is still intact.
PUT /tags/plants?permalink=flowers
Destroy the plants tag. This will remove the plants tag for each user in the system, along with all karma associated with that tag.
DELETE /tags/plants
Adjustments represent a change in karma for a given user, for a given tag.
They differ from tags and users in the way that they’re created and referenced; they’re not named explicitly by the client. Instead, they’re assigned an integer identifier by the karma server when they’re created.
Adjustments also have two optional attributes: object_uuid and action_timestamp. These attributes are only meaningful to a client, the Karma Server only stores them.
The Object UUID is intended to store an identifier the client uses to reference an object that relates to an adjustment. The Action Timestamp is intended to store a timestamp of the moment a user earned karma, before the karma was requested to or issued from the Karma Server.
Increment the karma in bob’s plant tag by three points. The “Location” header of the response redirects the client to the new adjustment.
POST /users/bob/tags/plants/adjustments?adjustment[value]=3
Decrement the karma in bob’s plant tag by one point. The “Location” header of the response redirects the client to the new adjustment.
POST /users/bob/tags/plants/adjustments?adjustment[value]=-1
Increment the karma in bob’s plant tag by three points and save an object identifier of ‘plant_id_3’.
POST /users/bob/tags/plants/adjustments?adjustment[value]=3&object_uuid='plant_id_3'
Increment the karma in bob’s plant tag by three points and save an action timestamp of ‘April 2nd at 3pm’ to be saved with the adjustment.
POST /users/bob/tags/plants/adjustments?adjustment[value]=3&action_timestamp='April 2nd at 3pm'
Save an object identifier of ‘plant_id_3’ and a action timestamp of ‘April 2nd at 3pm’ to be saved with a Karma adjustment. Append the following to a Karma Increment or Karma Decrement Adjustment.
&object_uuid='plant_id_3'&action_timestamp='April 2nd at 3pm'
Get the details for one particular adjustment from user Bob.
GET /users/bob/tags/plants/adjustments/245
Get a new adjustment object to see what fields it consists of and to have a sandbox adjustment object to play around with.
GET /users/bob/tags/plants/adjustments/new
Returns a history of all karma adjustments for user “bob”. *not yet implemented*
GET /users/bob/adjustments
Returns a history of all karma adjustments for bob’s “plants” tag.
GET /users/bob/tags/plants/adjustments
Remove (undo) one particular adjustment for user Bob.
DELETE /users/bob/tags/plants/adjustments/245