Media Types

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
  2. Getting a Single Maze
  3. Moving Around the Maze
  4. Handling Errors

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