Formating the resource
In this section, you'll construct a series of XML documents to represent the resources that the RESTful races Web service will support.
The RESTful API you built in the preceding section for Acme Racing covers the network endpoints or URIs but not the resources. As far as REST is concerned, the format of the resources doesn't matter, as I mentioned earlier. You could pass XML or binary streams back and forth, for example.
XML is arguably the lingua franca of machine-to-machine communication in the context of business transactions, so it makes sense to construct a series of XML documents that the RESTful service will support. The domain for racing is fairly simple, and you can use an existing data model, so the task of defining a few XML documents that represent races and runners is straightforward.
For instance, a race can be defined in XML as in Listing 1:
Listing 1. XML document for a race
<race name="Mclean 1/2 Marathon" date="2008-05-12" distance="13.1" id="1"> <uri>/races/1</uri> <description/> </race>
Note that a
<race> has an
id and that Listing 1 includes a URI as part of the definition of a race. This is a key aspect of REST and indeed, the Web — resources are related and should be linked together. Accordingly, a
<race> always contains a
<uri> element describing its RESTful representation. The XML in Listing 1 is arguably the response of a
GET request to /races/1.
To create a new race, you could omit the
id aspect (because managing unique IDs is something the application you're building here controls). This implies you could exclude the
<uri> element as well. Consequently, a
POST request would look something like Listing 2:
Listing 2. Race-creation XML
<race name="Limerick 2008 Half" date="2008-05-12" distance="13.4"> <description>erin go braugh and have a good time!</description> </race>
What about runners? A runner is connected to race, right? So the
<race> element supports holding one or more
<runner> elements, as shown in Listing 3:
Listing 3. Runners associated with a race
<race name="Limerick 200 Half" date="2008-05-12" distance="13.4" id="9"> <uri>races/9</uri> <description>erin go braugh and have a good time!</description> <runners> <runner first_name="Linda" last_name="Smith" age="25" id="21"> <uri>/races/9/runner/21</uri> </runner> <runner first_name="Andrew" last_name="Glover" age="22" id="20"> <uri>/races/9/runner/20</uri> </runner> </runners> </race>
The XML document in Listing 3, for example, is what would be returned via the URI /race/race_id/runner. The API also supports CRUD operations performed on a single runner via the URI /race/race_id/runner/runner_id.
Accordingly, the XML for these CRUD actions looks like Listing 4:
Listing 4. CRUD XML
<race name="Mclean 1/2 Marathon" date="2008-05-12" distance="13.1" id="1"> <uri>/races1</uri> <description /> <runner first_name="Andrew" last_name="Glover" age="32" id="1"> <uri>/races/1/runner/1</uri> <result time="100.04" place="45" /> </runner> </race>
Note that if the race is already complete, a runner's results can be included in the XML document. Remember, using a
POST request means creating a runner; consequently, the
id attribute would not be present.