[Ocs] First draft of Achievements module

[Dan Leinir Turthra Jensen]

Hi again!

  Please check the updated version: http://paste.kde.org/2460/ :) The 
following is still replies to Cornelius' replies to me. I've attempted to take 
into account all the comments given to me from the surprising number of people 
who came forward to help with it :)

On Thursday 13 Jan 2011 15:11:22 Cornelius Schumacher wrote:
> 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?

  Basically i have been trying to come up with a way of ensuring this which 
did not include some kind of super-secret-secret-keypassphrase server/client 
handshake thing as employed in the various closed source solutions, and have 
come up empty. So, what we (Daskreech and i) came up with after a discussion 
on IRC last night was to add a clientside timestamp to the calls which set 
progress. The reason for this would be that it allows for some further 
serverside logging of the user's progress updates, so that moderators and such 
can base their decisions on more data.

> * 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.

  This is a good question. Yes, i would like for this, but i am wondering how 
to add it sensibly. Any ideas for that one? :)

> * In the XML there is a tag "contentID". To have consistent spelling I
> would recommend to change that to "content_id".

  done, thanks :)

> * It's not explicitly stated, but I assume the achievement id unique across
> all content. Maybe that should be stated explicitly.

  That's the idea, yes - not strictly required, i guess, but that's the idea. 
So yeah, added a comment to that effect :)

> * 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.

  Right, i moved it around to make it 404 errors :)

> * What's the difference between setting progress to zero and resetting
> progress? Are there really to different calls needed.

  This is primarily because you can only set progress to a higher level than 
it was before. However, with the new types added due to discussions with a 
person who used to work with an existing framework for achievement tracking, 
resetting by storing 0 wouldn't work anyway any longer, because we just have 
so many other possibilities. Plus, of course, the argument that actually 
having a call to reset the progress is equivalent to delete (which i have done 
it as now)

  Finally, i have taken your suggestion for a more RESTful API into account, 
and restructured the spec considerably. Thank you greatly for the help! :)

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

-- 
..Dan // Leinir..
http://leinir.dk/

                          Co-
                            existence
                          or no
                            existence

                          - Piet Hein