How REST Works

Generally speaking, a REST request will involve sending a request to a special URL (similar to what you would see after filling out a form using the GET method), then receiving an XML document containing the server's response. The XML response is then parsed, and the desired information is extracted and acted upon.

Each REST request generally has several common elements:

• Endpoint URL — The full address for the desired script. A REST service might have only a single script that handles all request types, or different scripts for different request types.

• Developer ID — Most REST services require some sort of developer ID or key to be sent with each request. This identifies the origin of the request and is generally used for tracking purposes. Some services may use this value to limit the number of queries run during a given time frame.

• Desired action — Few servers have a unique endpoint for all possible requests. As such, it is generally required to include the desired action in the request.

• Parameters — Several parameters will need to be included with the request to provide the requested action with some context (for example, the desired action might be a search; the parameters might be a type, and the keywords values of book and style).

With those elements in mind, you can create a theoretical request:

Here a request is sent to the endpoint http://library.example.com/api.php, with a developer key of 123. The desired action is search, and type and keyword parameters are included with values of book and style. Given that request, the response would look something like this:

<?xml version="1.0" encoding=" UTF-8"?>
<LibraryAPI xmlns="http://library.example.com/api/spec">
<Request>
<RequestId>123a456</RequestId>
<Parameters>
<Argument Name="devkey" Value="123" />
<Argument Name="action" Value=" search" />
<Argument Name="type" Value=" book" />

<Argument Name="keyword" Value=" style" />
</Parameters>
</Request>
<Response>
<ResultCount>2</ResultCount>
<Item>
<Title>Style Book Vol 1</Title>
<Status>Out</Status>
<Holds>3</Holds>
<CopiesOnHand>2</CopiesOnHand>
<Author>Jon Doe</Author>
</Item>
<Item>
<Title>Style Book Vol 2</Title>
<Status>In</Status>
<Holds>0</Holds>
<CopiesOnHand>1</CopiesOnHand>
<Author>Jon Doe</Author>
</Item>
</Response>
</LibraryAPI>

You can see that the response has several structural elements. First, it declares itself to be XML 1.0 and uses UTF-8 for encoding. The LibraryAPI element is the root element of this document and includes the specified namespaces. Second, the Request section; it is common for REST requests to include all information sent with the request in the response. This adds clarity, and can ease programming on the requestor's end. Here you see each of the four elements passed to the service.

Finally, looking a bit closer, you will notice that in this case the response has returned some metadata about the results, shown in the ResultCount tag, along with the result items themselves. For this request you see each book is encapsulated within an Item element, which has five children that describe specific attributes of the books.