Skip to content
No description or website provided.
Ruby JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.bundle
app
config
db
doc
features
lib/tasks
public
script
sources
spec
vendor/plugins
.gitignore
Capfile
Gemfile
Gemfile.lock
README.rdoc
Rakefile
VERSION

README.rdoc

Karma Server

Customer: Marine Biological Laboratory / Encyclopedia of Life

Basecamp: westarete.basecamphq.com/projects/3622221

A web service provider for tracking “karma” points of users who are distributed across several separate web applications.

Mime Types

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.

Resources

Users

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 list of all Users

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

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

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 on a User

Get information about user bob. This would include the creation time, bob's karma score, latest activity, related URI's, etc.

GET /users/bob

Update a User

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 a User

Delete user “bob”, along with all of his karma and karma history.

DELETE /users/bob

Get User's Karma Summary

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

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 list of all Tags

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

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 Tag

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 on a Tag

Get information about the tag “plants”.

GET /tags/plants

Update a Tag

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

Delete a tag

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

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 Karma

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 Karma

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

Save an optional Object UUID with a Karma Adjustment

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'

Save an optional Time of Action with a Karma Adjustment

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 optional Object UUID and Time of Action with a Karma Adjustment

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'

View an Adjustment

Get the details for one particular adjustment from user Bob.

GET /users/bob/tags/plants/adjustments/245

View a new adjustment

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

View the History of All Adjustments for a User

Returns a history of all karma adjustments for user “bob”. *not yet implemented*

GET /users/bob/adjustments

View the History of All Adjustments for a User's Tag

Returns a history of all karma adjustments for bob's “plants” tag.

GET /users/bob/tags/plants/adjustments

Delete an adjustment

Remove (undo) one particular adjustment for user Bob.

DELETE /users/bob/tags/plants/adjustments/245
Something went wrong with that request. Please try again.