RESTful初探之二（Off to the races:Building a RESTful API）

[size=large]Imagine an online application that manages races in which contestants run various distances(such as the Chicago Marathon).The application manages races(or events)and the runners associated with them.And it reports a particular runner's time (how long it took to run the race) and rank(what place the runner finished in).The race-management company,Acme Racing,wants you to build a RESTful Web service that enables sponsors to create new races and racers for a particular race,and that can provide official results for a particular race.
想象一个管理很多选手跑很多种距离的比赛的在线应用，这个应用管理比赛和参赛的选手。他报道制定选手的时间和名次。Acme Racing公司希望创建一个RESTful的Web服务，能够支持为指定的比赛创建新比赛和选手，并且提供官方结果。

Acme Racing already has a legacy fat-client application that supports similar requirements and leverages a simple database along with a domain model.Thus,the job of exposing this functionality is all that's left to do.Remember that the beauty of REST it its implicit loose coupling with an underlying application. accordingly,your job,at the moment,isn't to worry about the data model or the technology associated with it-it's to construct a RESTful API that supports the company's requirements.
Acme Racing 公司有个遗留的富客户端应用支持类似需求，并利用一个简单的基于数据库的对象模型。我们的工作就是暴露这些功能。记住REST的优美之处在于隐含的低耦合的底层应用。
__________________________________________________________________________________

[color=red]Race URIs(uniform resource identifies)统一资源标示[/color]
Acme Races would like sponsors to be able to:
*View the details of existing races
*Create new races
*Update existing races
*Delete races
Beacuse REST boils down to named resources,the API becomes a series of URI patterns,and the behavior associated with a resource is invoked via standard HTTP commands.
因为REST可归结于命名资源，API成为一系列的URI模式。并且通过标准的HTTP命令使行为联系资源被调用。

As you can see,the client's requirements map nicely to CRUD. And as you konw from Table1,REST supports CRUD via the HTTP POST,GET,PUT,and DELETE requests,respectively,Accordingly,a base RESTful URI that supports these requirements could be http://racing.acme.com/race.Note that in this case,race is the resource clients would work with.
用户的需求很好的映射为CRUD。REST通过HTTP POST,GET,PUT,and DELETE来支持CRUD。因此，一个基础的支持这些需求的RESTful URI是http://racing.acme.com/race。注意这种情况下，race是资源客户将操作的。

Invoking this URI with an HTTP GET would return a list of races.(Don't worry about the format of the response just yet.)To add a new race,you would invoke the same URI with an HTTP POST containing the appropriate information(for instance,an XML document containing required race information,such as name,date,and distance).
调用这个URI进行HTTP GET请求会返回一列races。（这时先别考虑如何格式化response）添加一个新的race，你要提交相同的URI，只需URI使用POST提交，并且包含一些适当的信息（这个实例，一个XML文件包含race需求的信息，如名称，时间和距离）。

For updating and deleting existing races,you would need to act on a particular instance of a race.Accordingly,individual races can be addressed with a URI of http://racing.acme.com/race/race_id.In this case ,race_id represents a placeholder for any race identifier(such as 1 or 600 meter).Consequently,viewing an existing race instance would be an HTTP GET to that URI:updating or deleting a race would be a PUT or DELETE request,respectively.
修改和删除已经存在的races，你将需要按照具体的实例来处理race。因此，不同个体的races可以被URI定位为http://racing.acme.com/race/race_id。这种情况下，race_id代表了一个任何race标示的占位符。因此，查看的URI是GET,删除时DELETE,修改时PUT.

Acme would also like the service to let users view individual data for a particular runner in a particular race.They'd like their service to support:
*Obtaining all runners for a particular race. This data should also include run times and ranks for a race that's already completed.
*Creating one or more runners for a particular race.
*Updating a runner's information(such as age)for a particular race.
*Deleting a runner for aparticular race.
公司要求为用户提供这样的服务：查看指定race的指定runner。包括获得指定race所有runners的信息。为race创建runner，为race修改runner及删除信息。
Acme would also like the service to let users view individual data for a particular runner in a particular race.
公司要求为用户提供查看指定race指定runner的个人资料的服务。

Just as with races,applying RESTful URIs to runners associated with a race is a logical exercise.Viewing all runners for a particular race,for example,would be implemented via a GET request to http://racing.acme.com/race/race_id/runner.
RESTful URIs同样适用于关联race的runner。

Obtaining individual data for a runner in a race would be addressed as http://racing.acme.com/race/race_id/runner/runner_id.
得到race的runner的个人数据可以定位为..

Just like race_id,runner_id is a placeholder for the logical implementation of IDs,which could be numbers,names,alphanumeric combinations,and so on.
正如race_id,runner_is是逻辑实现的占位符，他们可以使数字，名称，字母数字组合等等。

Adding runners to a race would be a POST request to http://racing.acme.com/race/race_id/runner. Updating or deleting particular runners would be, respectively, PUT and DELETE requests to http://racing.acme.com/race/race_id/runner/runner_id.
Thus, these URIs (each supporting some or all of the four standard HTTP requests) capture Acme Racing's requirements:
/race
/race/race_id
/race/race_id/runner
/race/race_id/runner/runner_id
Remember, a particular URI can map to more than one HTTP verb (for instance, applying an HTTP GET to /race returns data; applying a POST with appropriate data creates data on the server). Accordingly, some HTTP commands wouldn't be implemented. For example, /race wouldn't support the DELETE command (Acme Racing wouldn't want to delete all races); /race/race_id could support the DELETE command because removing a particular instance of a race is a business requirement.
[/size]