Server API

The Mobile Trail Mapping server exposes a RESTful API for mobile applications to call. This API consists of a number of HTTP-accessible "endpoints," each of which respond to GET or POST requests.

General Rules

The method of access to be used for each endpoint varies depending on the action the user wishes to perform:

• If the action will change data in any way (more formally, if it alters the database state), it should be submitted via POST
• If the action is read-only and does not make any changes to data stored in the server database, it should be submitted via GET

In addition, endpoints which take POST requests may respond differently based on the credentials they are supplied. These credentials should be passed by way of POST variables. The variables expected are:

• user shall contain the username to log in using
• pwhash shall contain an SHA-1 hash of the user's password string

Endpoints

Category

• /category/add: Add a new trail point category for use in defining trail points.
• /category/get: Provide the list of currently defined categories that trail points may belong to.

Condition

• /condition/add: Add a new trail condition for use in reporting information about trail points.
• /condition/get: Provide the list of currently defined conditions that may be applied to trail points.

Images

• /image/get/point_id: Provide the number of images that are available for a particular trail point.
• /image/get/point_id/image_id: Provide the image data for the requested image related to the given trail point.
• /image/upload: Allow users to upload, via a Web form, new images for use in the server. This endpoint allows users to upload an image and specifiy the point that it is associated with. The point must exist prior to using this via /image/add. (Note: this endpoint is not accessed by a mobile application, but via a normal Web browser.)
• /image/add: Add an image to a particular trail point. Takes the following POST variables:
  • id: The id of the point to add this picture to.
  • file: The picture to add

Problems

• /problem/add: Add a problem with a description, title, user and picture. Takes the following POST varaibles:
  • lat: The latitude of the new point, given as a floating-point value
  • long: The longitude of the new point, given as a floating-point value
  • title: The title for the problem
  • desc: Description of the problem
  • file: Picture of the problem
  • user: User who is submitting the problem
• /problem/get: Return xml list of all the problems currently in the system

Trail points

• /point/get: Provide a list of trail points known to the MTM system.
• /point/add: Add a trail point with latitude, longitude, and connections. The connections must be specified as IDs of other trail points. Takes the following POST variables:
  • lat: The latitude of the new point, given as a floating-point value
  • long: The longitude of the new point, given as a floating-point value
  • desc: The description of the new point
  • title: The title of the new point
  • category: The name of the category to which the new point belongs
  • condition: The description of the condition to which the new point belongs
  • trail: The name of the trail to which the new point belongs
  • connections: A serialized list of point IDs to which to connect. Uses a comma as point ID separator (e.g. 2,3,5)
• /point/add/coords: Add a trail point with latitude, longitude, and connections. The connections must be specified as lat-long pairs. (Note: this is a convenience endpoint. Most point additions should use /point/add.) Takes the following POST variables:
  • lat: The latitude of the new point, given as a floating-point value
  • long: The longitude of the new point, given as a floating-point value
  • desc: The description of the new point
  • title: The title of the new point
  • category: The name of the category to which the new point belongs
  • condition: The description of the condition to which the new point belongs
  • trail: The name of the trail to which the new point belongs
  • connections: A serialized list of latitude-longitude pairs of the points to which to connect. Uses commas to separate pairs and colons to separate latitude and longitude (e.g. 10.000:20.000,30.000:40.000)

Trails

• /trail/add: Add a new trail to the system for tracking. Takes a single parameter, name, with the name of the trail to be created.
• /trail/get: Provide a list of trails known to the MTM system.

User management

• /user/add: Create a new user for authentication within the MTM system.
• /user/check: Get the authentication status of a user. Used for mobile applications to determine the privilege level of a given user account. Return values (as strings):
  • user: User is a regular registered user
  • admin: User is an administrator
  • invalid: User is not registered
• /user/toggle_admin: Toggle whether a registered user is an administrator. Takes one additional parameter (beyond authentication): user_to_change.