Sync

Upon obtaining an authentication token for a given user, FireRoad provides you access to that user's preferences, roads and schedules.

Preferences

/prefs/notes (GET), /prefs/set_notes (POST)

These endpoints handle read-write of notes, which the user can enter for any subject in the catalog. The format of the returned notes is a dictionary with the success key, and if that is true, a notes key containing a dictionary keyed by subject IDs.

/prefs/favorites (GET), /prefs/set_favorites (POST)

These endpoints handle read-write of favorite subjects. The format of the returned data is a dictionary with the success key, and if that is true, a favorites key containing a list of subject IDs.

/prefs/progress_overrides (GET), /prefs/set_progress_overrides (POST)

Deprecated. Use the progressOverrides key in the road file to store progress overrides.

These endpoints handle read-write of manual progress overrides, which the user can set for requirements lists to indicate progress toward completion. The format of the returned data is a dictionary with the success key, and if that is true, a progress_overrides key containing a dictionary keyed by requirements list key-paths (see the RequirementsListStatement implementation in the mobile app for more information).

/prefs/custom_courses (GET)

Retrieves the custom courses created by the user. Takes no input, and provides the list of custom courses in standard JSON course format under the custom_courses key of the returned dictionary.

/prefs/set_custom_course (POST)

Creates or updates a custom course. The input is a JSON dictionary containing the full description of a course to add or update (subject_id is required). By default, the course is set to "public": false (a value of true currently has no effect). Output has a success key indicating whether the update was successful.

/prefs/remove_custom_course (POST)

Removes a custom course from the user's list. The input is a JSON dictionary specifying the course to remove (subject_id is required). Output has a success key indicating whether the update was successful.

File Sync

/sync/roads (GET)

If a primary key is specified by the id query parameter, returns the contents of the given file as well as its last-modified agent. If no primary key is specified, returns a dictionary of primary-keys to metadata about each of the user's roads.

/sync/sync_road (POST)

This endpoint determines whether to change the remote copy of the file, update the local copy, or handle a sync conflict. The body of the request should be a JSON dictionary containing the following keys:

• id: The primary key of the road to update (don't pass if adding a new file)
• contents: The contents of the road to update
• changed: The local last-modified date of the road
• downloaded: The date of the last download of the road from the server
• name: The road name (required if adding a new file, or if renaming an existing road)
• agent: The name of the device submitting the change
• override: Whether to override conflicts

Returns a JSON dictionary that may update the above keys and/or add the following keys:

• success: Whether the file was successfully compared against its remote version
• error: A console error if success is false
• error_msg: A user-facing error to display if success is false
• result: A string indicating the result of the operation, e.g. "update_remote", "update_local", "conflict", or "no_change"
• other_name, other_agent, other_date, other_contents, this_agent, this_date: Keys that are specified in the case of a conflict. In this case, the user should select whether to keep the local copy, the remote copy, or both. If keeping the local copy, the client should submit a new sync_road request with the override flag set to true.

/sync/delete_road (POST)

Deletes the file specified by the id key in the body of the request.

/sync/schedules, /sync/sync_schedule, /sync/delete_schedule

Analogous to the above endpoints, but for schedules.