[Ocs] First draft of Achievements module

[Dan Leinir Turthra Jensen]

On Thursday 03 Feb 2011 18:03:49 Frank Karlitschek wrote:
> Hi Dan,
> 
> I thing the module specification looks good and there was no further
> feedback on the list. So I think we can put your draft into the OCS spec.
> 
> Can you merge this into the current 1.6 spec?

  Ten-four, shall do this momentarily! :)

> I will also draft a few changes witch where requested by some people during
> the Linux App Store meeting (AppStream) 2 weeks ago.
> 
> I plan to release everything together as 1.7 in a few days.

  Sounds like a plan to me :)

> This will be an intermediate release before 2.0 which should also happen
> soon.

  Speaking of which, do we have any ideas yet about the OCS planning sprint 
yet? :)

> Cheers
> Frank
> 
> On 14.01.2011, at 02:01, Dan Leinir Turthra Jensen wrote:
> > 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>
> 
> --
> Frank Karlitschek
> karlitschek at kde.org

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

                          Co-
                            existence
                          or no
                            existence

                          - Piet Hein