In part 1 of this series, I laid out my goals for a RESTful chess service, based on the RESTful Web Services book from the O’Reilly series. The authors present a procedure for designing services, the first two of which are:
- Figure out the data set
- Split the data set into resources
The use cases I’m looking to support are chess tournament directors (TD) reporting games during events and people searching for events, players, and games. That identifies my three major parts of the data set right there. There are other elements I could use. Chess has a standard notation for describing a game called PGN. Here’s an example from a small tournament I played in years ago:
The format is pretty straightforward, I think. Metadata are at the top, followed by a list of moves in algebraic notation. If the move notation doesn’t make sense to you, don’t worry about it — that’s not important for this exercise.
This is a game I played in a small USCF event. You’ll notice the name of the event is “First Saturday Quads”. As you might guess, that’s not a unique name — other sites can have an event with the same name. Really it’s the combination of Event, Site, and Date that uniquely identify a particular tournament — and the date is a little dicey, since an event may span multiple days. This won’t be a problem for a TD uploading a game, as all the information is there. For search and browsing, I won’t have any explicit representation of a Tournament, although the service will allow a user to find all the games in a tournament.
The authors tell us that a resource is “anything interesting enough to be the target of a hypertext link.” They also list three kinds of resources web services commonly exposed.
1) Predefined, one-off resources
The given examples are top-level directories of available resources, or the home page of a web site. For my service, I will have a base resource that takes a collections approach, simply returning a list of links to the other resources available from the service.
2) A resource for every object exposed through the service
The objects I’ve decided to expose are events, players and games. Each event, player and game will be a unique resource available through the service. Events will be collections of games. We actually won’t be storing much information about players, only what is included in the game reports, so player resources will similarly be collections of games.
3) Resources representing results of algorithms
This service will define only one algorithm: search. The results will be collections of objects that match the search criteria. There will really be three ways to search, one for returning each type of object.
In the next part of this series, I’ll work through the remaining steps for the Game resource.
Tags: chess, resources, rest, xml