Routes API

The Routes API

• allows to share routes between RouteConverter users
• is open to all other programs and users
• aims at quality not quantity
• uses as little structure as possible
• offers a simple RESTful interface

This description aims to serve as a short reference for developers building tools that work with Routes API.

Authentication

All modifying Routes API methods require authentication. Currently HTTP Basic Authentication is the only supported authentication scheme.

RESTful Webservice

The Routes API tries to conform as much as possible to the design principles of Representational State Transfer (REST). It presently supports GPX 1.1 as its data format.

Parameters

Some Routes API methods take optional or requisite parameters. Where applicable, I've documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

HTTP Status Codes

The Routes API attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:

• 200 OK: The request has succeeded.
• 201 Created: The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI given by a Location header field.
• 401 Not Authorized: The request requires user authentication. Either you need to provide authentication credentials, or the credentials provided aren't valid.
• 403 Forbidden: The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. An accompanying error message explains why.
• 404 Not Found: The server has not found anything matching the Request-URI. Either you're requesting an invalid URI or the resource in question doesn't exist.
• 412 Precondition Failed: A precondition to fulfill the request was not met. An accompanying error message explains why.
• 500 Internal Server Error: RouteCatalog did something wrong. Please post to the forum about it and I will investigate.

Category Methods

GET

Returns information about a category including links to subcategories and links to routes of this category.

• URL: http://www.routeconverter.com/catalog/categories/<path>.<format>
• Parameters:
  • <path> optional, string, subcategories separated by a slash
  • <format> required, string, currently only gpx supported

POST

Creates a category <New Category> below a given category.

• URL: http://www.routeconverter.com/catalog/categories/<path>.<format>
• Parameters:
  • <path> optional, string, subcategories separated by a slash
  • <format> required, string, currently only gpx supported

• Payload: gpx containing the <New Category> as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
       xmlns="http://www.topografix.com/GPX/1/1"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                           http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>New Category</name>
      <metadata>
  </gpx>
  

• Result: 201 if successful, "Location" header contains the URL of the <New Category>

PUT

Updates a category. The authenticating user must have created the specified category.

• URL: http://www.routeconverter.com/catalog/categories/<path>.<format>
• Parameters:
  • <path> optional, string, subcategories separated by a slash
  • <format> required, string, currently only gpx supported

• Payload: gpx containing the updated name and category as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
       xmlns="http://www.topografix.com/GPX/1/1"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                           http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>Renamed Category</name>
          <keywords>Updated category path of the category</keywords>
      <metadata>
  </gpx>
  

• Result: 200 if successful

DELETE

Deletes a category. The authenticating user must have created the specified category.

• URL: http://www.routeconverter.com/catalog/categories/<path>.<format>
• Parameters:
  • <path> optional, string, subcategories separated by a slash
  • <format> required, string, currently only gpx supported
• Result: 200 if successful

Route Methods

GET

Returns information about a route including a link to the file representation of this route.

• URL: http://www.routeconverter.com/catalog/routes/<id>.<format>
• Parameters:
  • <id> required, number
  • <format> required, string, currently only gpx supported

POST

Creates a route <New Route>.

• URL: http://www.routeconverter.com/catalog/routes/
• Parameters: none

• Payload: gpx containing the <New Route> as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
       xmlns="http://www.topografix.com/GPX/1/1"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                           http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>New Route</name>
          <desc>Description of the new route</desc>
          <keywords>Category path of the new route</keywords>
          <link href="URL to the file of the new route"/>
      <metadata>
  </gpx>
  

• Result: 201 if successful, "Location" header contains the URL of the <New Route>

PUT

Updates a route. The authenticating user must have created the specified route.

• URL: http://www.routeconverter.com/catalog/routes/<id>.<format>
• Parameters:
  • <id> required, number
  • <format> required, string, currently only gpx supported

• Payload: gpx containing the updated name, description, category and file URL as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
       xmlns="http://www.topografix.com/GPX/1/1"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                           http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>Renamed Route</name>
          <desc>Updated description of the route</desc>
          <keywords>Updated category path of the route</keywords>
          <link href="Updated URL to the file of the route"/>
      <metadata>
  </gpx>
  

• Result: 200 if successful

DELETE

Deletes a route. The authenticating user must have created the specified route.

• URL: http://www.routeconverter.com/catalog/routes/<id>.<format>
• Parameters:
  • <id> required, number
  • <format> required, string, currently only gpx supported
• Result: 200 if successful

File Methods

GET

Returns the file representation of a route.

• URL: http://www.routeconverter.com/catalog/files/<id>/
• Parameters:
  • <id> required, number
• Headers: "Content-Disposition" contains the file name

POST

Creates a file representation of a route.

• URL: http://www.routeconverter.com/catalog/files/
• Parameters: none
• Payload: file representation as bytes
• Result: 201 if successful, "Location" header contains the URL of the file representation

PUT

Updates a file representation of a route. The authenticating user must have created the specified file representation of the route.

• URL: http://www.routeconverter.com/catalog/files/<id>/
• Parameters:
  • <id> required, number
• Payload: file representation as bytes
• Result: 200 if successful

DELETE

Deletes a file representation of a route. The authenticating user must have created the specified file representation of a route.

• URL: http://www.routeconverter.com/catalog/files/<id>/
• Parameters:
  • <id> required, number
• Result: 200 if successful

User Methods

GET

Returns information about a user.

• URL: http://www.routeconverter.com/catalog/users/<name>.<format>
• Parameters:
  • <name> required, string
  • <format> required, string, currently only gpx supported

POST

Creates a user <New User>.

• URL: http://www.routeconverter.com/catalog/user/
• Parameters: none

• Payload: gpx containing the <New User> as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
       xmlns="http://www.topografix.com/GPX/1/1"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                           http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>New User</name>
          <extensions>
             <rcxx:userextension 
                 xmlns:rcxx="http://www.routeconverter.com/xmlschemas/RouteCatalogExtensions/1.0"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://www.routeconverter.com/xmlschemas/RouteCatalogExtensions/1.0 
                 http://www.routeconverter.com/xmlschemas/RouteCatalog10.xsd">
                  <rcxx:password>Password</rcxx:password>
                  <rcxx:email>NewUser@Domain.tld</rcxx:email>
                  <rcxx:firstname>FirstName</rcxx:firstname>
                  <rcxx:lastname>LastName</rcxx:lastname>
              </rcxx:userextension>
          </extensions>
      <metadata>
  </gpx>
  

• Result: 201 if successful, "Location" header contains the URL of the <New User>

PUT

Updates a user. The authenticating user must be the specified user.

• URL: http://www.routeconverter.com/catalog/users/<name>.<format>
• Parameters:
  • <name> required, string
  • <format> required, string, currently only gpx supported

• Payload: gpx containing the updated name, description, category and file URL as

  <?xml version="1.0" encoding="UTF-8"?>
  <gpx version="1.1" creator="Your Client"
      xmlns="http://www.topografix.com/GPX/1/1"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.topografix.com/GPX/1/1
                          http://www.topografix.com/GPX/1/1/gpx.xsd">
      <metadata>
          <name>New User</name>
          <extensions>
              <rcxx:userextension 
                 xmlns:rcxx="http://www.routeconverter.com/xmlschemas/RouteCatalogExtensions/1.0"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://www.routeconverter.com/xmlschemas/RouteCatalogExtensions/1.0 
                 http://www.routeconverter.com/xmlschemas/RouteCatalog10.xsd">
                  <rcxx:password>Changed Password</rcxx:password>
                  <rcxx:email>ChangedUser@Domain.tld</rcxx:email>
                  <rcxx:firstname>Changed First Name</rcxx:firstname>
                  <rcxx:lastname>Changed Last Name</rcxx:lastname>
              </rcxx:userextension>
          </extensions>
      <metadata>
  </gpx>
  

• Result: 200 if successful

DELETE

Deletes a user. The authenticating user be the specified user.

• URL: http://www.routeconverter.com/catalog/users/<name>.<format>
• Parameters:
  • <name> required, string
  • <format> required, string, currently only gpx supported
• Result: 200 if successful