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