[Ocs] First draft of Achievements module

[Cornelius Schumacher]

On Thursday 13 January 2011 Dan Leinir Turthra Jensen wrote:
> 
>   As some of you know already, the Gluon project, in particular the
> GamingFreedom.org site, is basing its social interaction features on OCS.
> Since we are all about gaming, we will obviously be needing some
> achievement system. However, rather than simply jumping at it and creating
> something useful only for games, with Frank Karlitschek's blessing i have
> spent the last couple of days working on a first draft of the
> specification for an OCS extension module for achievements. Please find
> this draft in the attached txt file.

Nice. I have a couple of comments and questions:

* It's trivial to fake achievement progress by just operating the API, e.g. 
with a simple curl call on the command line. Is this a problem?
* Is there a mechanism needed to manage visibility of achievement progress? So 
a user could decide to only show his achievements to his friends or to no one 
at all.
* In the XML there is a tag "contentID". To have consistent spelling I would 
recommend to change that to "content_id".
* It's not explicitly stated, but I assume the achievement id unique across 
all content. Maybe that should be stated explicitly.
* Some of the status codes are redundant with HTTP codes, like achievement 
doesn't exist, which should give a 404 response code on the HTTP level. This 
might not be a problem, provided, that the internal and the HTTP codes are 
consistent. To avoid this in advance, it might be nice to remove the redundant 
internal codes from the XML. Not sure, though. 
* What's the difference between setting progress to zero and resetting 
progress? Are there really to different calls needed.

As a last comment, I would propose a different URL scheme to make the API more 
REST-like. The idea would basically be to have two HTTP resources, one 
representing the general achievement data, and another one for the user's 
progress, plus a POST call for setting progress. This is how the scheme would 
look like:

# General achievement data

Get list of available achievements for content:

GET achievements/content/<content_id>

Create new

POST achievements/content/<content_id>

Get one:

GET achievements/content/<content_id>/<achievement_id>

Edit one:

PUT achievements/content/<content_id>/<achievement_id>

Delete one:

DELETE achievements/content/<content_id>/<achievement_id>


# User-specific achievement data (including progress data)

Get all achievements for given user for all contents:

GET achievements/user/<user_id>

Get all achievements for given user for given content:

GET achievements/user/<user_id>?content_id=<content_id>

Get specific achievement:

GET achievements/user/<user_id>/<achievement_id>


# Set progress

POST achievements/progress/<achievement_id>?progress=<value>

-- 
Cornelius Schumacher <schumacher at kde.org>