... the user friendly GPS tool

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.

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.

Route Methods

GET

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

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.

File Methods

GET

Returns the file representation of a route.

POST

Creates a file representation of a route.

PUT

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

DELETE

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

User Methods

GET

Returns information about a user.

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.


Page was requested in English but we've found only .

Please select the language to translate this page to: