Maze+XML - Tutorial
Description
This page contains a number of simple "walk-through" examples showing how to use the Maze+XML media-type to share state information between client and server.
Additional information about the Maze+XML media type can be found in the Document Format and Examples section of this documentation.
1.
Getting a List of Mazes
The Maze+XML media type supports returning a list of available mazes. A server returning a list of mazes may also supports the ability to add a new maze to the collection.
1.1.
Collection Document
The Maze+XML media type can be used to return a list of available mazes. The response to this request is referred to as a Collection document.
Clients can request a list of available mazes by sending an HTTP GET request to the server.
*** REQUEST GET /mazes/ HTTP/1.1 Host: www.example.org Accept: application/vnd.amundsen.maze+xml
Servers should respond to any valid requests to a collection URI with a collection document. Below is a simple example.
*** RESPONSE HTTP/1.1 200 OK Content-Type: application/vnd.amundsen.maze+xml Content-Length: XXX <maze> <collection href="http://www.example.org/mazes/"> <link href="http://www.example.org/mazes/1" rel="maze" id="m3"/> <link href="http://www.example.org/mazes/2" rel="maze" id="m2"/> <link href="http://www.example.org/mazes/3" rel="maze" id="m3"/> </collection> </maze>
1.2.
Adding to the Collection
Servers may allow users to add new mazes to the collection. If this is true, the URI returned in the <collection> element SHOULD be used. The exact details of how to add a new maze to the collection is beyond the scope of this document. Servers may define their own required and optional parameters, select which media types can be used to send data to the server, and which application-level protocol(s) can be used (HTTP, XMPP, etc.).
Below is an example showing a server that supports the HTTP POST method and the application/x-www-form-urlencoded
media type to send a single parameter (size
).
In this case the server will generate a simple connected square maze where each side has a maximum number
of cells equal to the parameter value.
*** REQUEST POST /mazes/ HTTP/1.1 Host: www.example.org Content-Type: application/x-www-form-urlencoded Content-Length: XXX size=10 *** RESPONSE HTTP/1.1 201 Created Location: http://www.example.org/mazes/1
NOTE: Using HTTP POST in the manner shown here is not required. Servers may, for example, support HTTP PUT, FTP STOR, etc to add new mazes to the collection, may support a wide range of parameters, and may even allow clients to upload fully defined mazes using any number of media types (JSON, HTML, CSV, etc).
2.
Getting a Single Maze
3.
Moving Around the Maze
4.
Handling Errors
Update History
- 2010-12-08
Initial post