This page is intended to provide ongoing updates and information regarding the SDG rewrite.
There are still questions regarding what language to use for the RESTful rewrite. My initial desire was to use Perl as it has a very nice REST module that works as an Apache handler. My concern was that the speed bottlenecks we've been experiencing were related more to Perl than to anything else and so I moved to a C++-based approach. This is still possible, but involves a huge amount of work that's more than a little daunting. Further debates have convinced me to explore more detailed profiling and attempting to keep the Perl code (particularly for the games) that has already been written. That is the process currently underway.
The new RESTful interface will use HTTPS. I have obtained certificates from the free CA CACert and am in the assurance process to make the certs as complete as possible. GET requests to the server will not require authentication of any kind. This will allow unregistered users to explore the site and observe games. PUT, POST, and DELETE requests on the other hand (that includes making moves, issuing new challenges, and chatting) will require authentication. The existing database will of course still be used combined with basic web auth. I'm also in the process of enabling me to issue sign-on certs to those who wish them, so that usernames and passwords do not necessarily have to be used at all.
REST is an architectural principle, not a specific design or implementation. It exposes your web service as a group of nouns as opposed to verbs. Games, users, tournaments, statistics will all be accessible as resources. Using the basic HTTP protocols GET, POST, PUT, and DELETE, actions are performed on these resources. The average user will not have to worry about what all this means or how it works. A new SDG website will sit as a front-end to the new service and allow you to perform all the tasks you do already. What this does is allow other hackers to devise their own front-ends, submit various themes, syndicate, or otherwise munge game data in a much more flexible and accessible way. If someone wants to create a new Flash or Java front end to a relatively complex game, it can be trivially made available. This will also allow me to build-in internationalization front the ground up, making things easier for non-English speakers. This migration process will not disturb normal SDG operations as all coding and testing is being done on test machines. Once everything is ready the new site will be migrated as a whole. No past game data will be lost.
The server will emit XML documents that adhere to custom-written XML Schemas (which I will make available for review soon). These schemas will encapsulate game states, user information, tournaments, etc…
As it stands the top level resources will include:
/games/challenges/users/tournaments/ladders/info/koans
It is an important aspect of RESTful design, however, that URIs be opaque. This means that the client should not have to know in advance how your entire site is structured. A simple request to / will return a list of the top-level resources. This allows the implementation to change if necessary without impacting clients.
/games/(open|closed|all)/(NAME|all) will return a list of open/closed games of a particular type (Homeworlds, Palisade, etc…)./games/ID# will return the full data of the specific game requested./games/ID#/INDEX# will return the full Position data at the given offset. 0 represents the starting position before any moves have been made. n-1 represent each move in sequence. Negative integers start at the end of the list, ergo, -1 is the most recent game position./games/ID#/INDEX#/moves will return a list of moves for the given position (if available)/games/ID#/clock will return the clock status of a specific game./games/ID#/players will return links to /user resources of those participating in the specific game./games/ID#/variants will return a list of variants in use for that specific game./games/ID#/moves will return a list of moves for the current position (if available)/games/ID#/chat/(all|system|players) will return just the chat log for the requested game/game/ID# resource is how one chats and submits moves./game/ID#/clock|variants|players resource allows one to freeze/thaw a clock, add/remove variants, or resign/boot a player./challenges will return a list of links to all open challenges./challenges/available will return a list of links to open challenges which you can accept (which have open slots or meet the forced score requirements)./challenges/NAME will return all challenges for a specific game type./challenges/available/NAME returns a list of challenges for a specific game type you can actually accept./challenges/ID# returns the full data of an existing challenge./challenges/NAME resource will create a new challenge./challenges/ID# resource allows you to join/leave an open challenge. If the last person leaves then resource is automatically purged./challenges/ID# object can be done only by the initiator and forcibly removes the challenge. Leaving the challenge via POST results in the same thing if you are the last person to leave./users will return a list of links to all registered users./users/trophies will return a list of all trophies held by all active players./users/NAME will return the full data regarding the specified user./users/NAME/trophies will return a list of trophies belonging to the specified player./users/NAME/ratings returns a list of links to the various game ratings for the given player./users/NAME/ratings/GAME returns the full data of the rating info for the given user and game./users/NAME/stats returns a list of links to the various “personal stats page” modules./users/NAME/states/MODULE returns the full data record for the specified user and module./users/NAME/messages returns a list of all private messages in the mail box. (Of course this will only be accessible to the user in question./users/NAME/messages/new returns a list of private messages that have not yet been read./users/NAME/messages/ID# returns the full data of the message requested./users/NAME/povray returns a list of links to images in that user's Povray Playground./users/NAME/povray/ID# returns the full data of the povray image requested./users/NAME/messages resource will send the specified user a message./users/NAME/povray resource allows the owning user to post new code to their personal Povray Playground./users/NAME/messages/ID# resource of course removes said message. This is of course only accessible to the owner of the mail box./users/NAME/povray/ID# resource removes the specified image from that user's Povray Playground./tournaments returns a list of links to all open, closed, and pending tournaments./tournaments/open|closed|pending returns a list of links to the appropriate tournaments./tournaments/ID# returns the full data of the requested tournament./tournaments/ID#/participants returns a list of user records of those participating in the tournament./tournaments/ID#/moderators returns a list of user records of those moderating the tournament./tournaments/ID#/games returns a list of gameID links of games associated with this tournament./tournaments/ID#/winner returns a list of user records listed as the winner(s) of the tournament./tournaments/ID# resource allows the moderators to make basic changes./tournaments/ID#/participants resource adds you to a pending tournament's list./tournaments/ID#/games resource allows moderators to start games./tournaments/ID#/winner resource allows moderators to declare a tournament winner./tournament/ID# resource purges the tournament and is available to tournament moderators but should rarely be used./ladders returns a list of links to all existing SDG ladders./ladders/in|active returns a list of active or inactive ladders (currently less than 6 participants)./ladders/log returns the full activity log for all existing ladders./ladders/ID# returns the full data record of the requested ladder./ladders/ID#/standings returns the list of participants and their various standings./ladders/ID#/standings/NAME returns the standing data of a particular user./ladders/ID#/games returns a list of links to games associated with this ladder./ladders/ID#/games/open|closed does as you would expect./ladders/ID#/log returns the full ladder activity log./ladders/ID#/standings/NAME resource allows one to join a ladder./ladders/ID#/games resource allows you to challenge others by creating a matching /challenges/ID# resource./challenges/ID# resource generated by the initial POST allows the challengee to accept or reject the challenge./ladders/ID#/standings/NAME resource removes you from the ladder.This is a little more generic and could well be further subdivided or reorganized. Feedback welcome.
/info/games returns a list of links to the information on all active games./info/games/NAME returns the full data record for the specific game./info/games/NAME/ratings returns the ratings and comments made about this game./info/stats returns a list of links to the various leaderboard modules./info/stats/MODULE returns the full data record for the specified leaderboard module./info/games/NAME/ratings resource adds/updates your rating and comment.This resource encapsulates the Povray Library. This resource has the potential of abuse and is closely logged and monitored. Please be conscious of bandwidth issues when downloading a large number of koans.
/koans resource returns a list of links to each individual koan in the library./koans/ID# resource returns the full data record for the specified koan./koans resource allows you to search the library./koans/ID# resource allows you to modify the entry in some way (usually indexing or commenting).