Maintenance API
- Phil Windley
Incompete
This API document is still undergoing changes and is incomplete.
The Maintenance API provides queries and events for interacting with the services that record maintenance on a vehicle. The model is as follows:
- Owners can set reminders can be either one-time or recurring. Reminders can be date or mileage based.
- Reminders that come due, and certain information from the vehicle such as diagnostic codes and other vehicle alerts such as a low battery become alerts.
- Owners can either defer (i.e. ignore) alerts or complete them.
- Completed alerts become maintenance items along with any maintenance items the owner enters directly.
The maintenance API comprises queries and events for dealing with and processing alerts, reminders, and maintenance items.
Query Domains
| development | b16x23 |
|---|---|
| production | fuse_maintenance |
The production version is always pre-pended to the production query domain with a underbar, so for version 1 of the API would use v1_fuse_maintenance as the query domain. In this document we will use the production query domain without the version. See Fuse Base URLs for more information on how to turn the descriptions shown here into a query URL.
Reminders
| Name | Type | Calculated | Description |
|---|---|---|---|
| id | uuid | yes | The internal system identifier for this reminder. Uses time the record is created as key. |
| kind | mileage or date | no | The type of reminder, by mileage or by date. |
| recurring | repeat or once | no | Describes whether the reminder recurs or not. |
| interval | integer | no | Time in seconds between a recurring, date reminder or the number of length units between a recurring, mileage reminder |
| activity | string | no | The activity being reminded |
| duedate | DateTime | yes | The date this reminder becomes due (25 years in the future for a mileage reminder) |
| duemileage | integer | yes | The mileage where this reminder becomes due (999999 for date reminders) |
| mileagestamp | integer | yes | Odometer reading when this reminder was created |
| timestamp | DateTime | yes | Time when this reminder was created |
DateTime is an ISO8901 formatted time. Returned times are always UTC
Queries
fuse_maintenance:reminders([<id>]|[<offset>, [<limit>]])
Query reminders. All parameters are optional. With <id>, the detailed data for a specific reminder is returned. Without <id>, <offset> and <limit> allow for pagination. Defaults for <offset> and <limit> are 0 and 10 respectively.
For example, to return the ten most recent alerts, you would simply for the following:
fuse_maintenance:reminders()
To return the data for a specific alert:
fuse_maintenance:reminders("73660370-145E-11E4-9670-1AACE71C24E1")
fuse_maintenance:activeReminders(<date>, <mileage>)
Find active reminders. The query takes a date and a mileage. Any reminders that would be due for that date, mileage pairs are returned.
fuse:new_reminder
A new reminder has been detected with the following attributes:
| Name | Type | Description |
|---|---|---|
| kind | mileage or date | The type of reminder, by mileage or by date. |
| recurring | repeat or once | Describes whether the reminder recurs or not. |
| interval | integer | Time in seconds between a recurring, date reminder or the number of length units between a recurring, mileage reminder |
| activity | string | The activity being reminded |
fuse:updated_reminder
An updated reminder has been detected. The attributes are the same as for fuse:new_reminder, except that an attribute called id, giving the identifier for the updated reminder is required.
fuse:unneeded_alert
Delete the reminder record with the given id.
| Name | Type | Description |
| id | DateTime | id for the record to delete |
Services
The following services are related to reminders
fuse:process_reminder
Selector:
select when fuse updated_milage
Synopsis:
Uses current mileage and current date to determine if there are any active reminders. Each active reminder is used to create a fuse:reminder_due event.
Raises:
fuse:reminder_due
fuse:create_alert_for_reason
Selector:
select when explicit reminder_due or fuse updated_battery or fuse updated_dtc or fuse updated_fuel_level
Synopsis:
Processes due reminders as well as events from the vehicle to create a new alert.
Raises:
fuse:new_alert
Alerts
Return Results
The Fuel API returns fuel details. A trip summary contains the following data fields
| Name | Type | Calculated | Description |
| id | Integer | yes | The internal system identifier for this alert. Uses time the record is created as key. |
| timestamp | DateTime | yes | The time of the purchase. Can be given or calculated. |
| troubleCodes | String Array | no | Trouble codes that generated alert, if any |
| odometer | Float | no | Odometer reading at fillup |
| activity | String | no | The activity associated with the trouble code (e.g. oil change, tire rotation, etc.) |
| reason | String | no | English language explanation for the record |
| reminderRef | UUID | yes | The ID of the reminder that generated this alert. Null if none. |
DateTime is an ISO8901 formatted time. Returned times are always UTC
Queries
fuse_maintenance:alerts([<id>]|[<offset>, [<limit>]])
Query alerts. All parameters are optional. With <id>, the detailed alert data for a specific alert is returned. Without <id>, <offset> and <limit> allow for pagination. Defaults for <offset> and <limit> are 0 and 10 respectively.
For example, to return the ten most recent alerts, you would simply for the following:
fuse_maintenance:alerts()
To return the data for a specific alert:
fuse_maintenance:alerts("73660370-145E-11E4-9670-1AACE71C24E1")
fuse_maintenance:fillupsByDate(<start>, <end>)
Query past fillups for those between a start and end time. Summary fillup data is returned. Times are expressed in ISO8901 format.
For example to find all the fillups for June 2014 in the US Mountain time zone:
fuse_maintenance:fillupsByDate(start="20140601T000000-0600", end="20140701T000000-0600")
Events
The following events are used defined for fillups in the Fuse API.
fuse:new_alert
A new fillup has been detected with the following attributes:
| Name | Type | Required | Description |
| troubleCodes | String Array | no | Trouble codes that generated alert, if any |
| odometer | Float | no | Odometer reading at fillup |
| activity | String | yes | no | The activity associated with the trouble code (e.g. oil change, tire rotation, etc.) |
| reason | String | no | English language reason for the alert. |
| reminderRef | UUID | no | yes | The ID of the reminder that generated this alert. Null if none. |
If a reminderRef is given, activity will be taken from that, otherwise, activity is required.
Odometer is taken from the vehicle's current odometer reading unless supplied.
fuse:updated_alert
An alert with the given ID is to be updated.
| Name | Type | Required | Description |
| id | Integer | yes | The internal system identifier for this trip. Uses time the record is created as key. |
| troubleCodes | String Array | no | Trouble codes that generated alert, if any |
| odometer | Float | no | Odometer reading at fillup |
| activity | String | no | The activity associated with the trouble code (e.g. oil change, tire rotation, etc.) |
| reason | String | no | English language reason for the alert. |
| reminderRef | UUID | no | The ID of the reminder that generated this alert. Null if none. |
Note: updates are not partial. You must supply all the parameters. This is likely to change in a future version of the API.
fuse:unneeded_alert
Delete the alert record with the given id.
| Name | Type | Description |
| id | DateTime | id for the record to delete |
Services
fuse_maintenance:record_fuel_purchase
Selector:
select when fuse new_fuel_purchase
Synopsis:
Records a new fuel purchase. Uses fuse_maintenance:update_fuel_purchase
Raises:
fuse_maintenace:update_fuel_purchase
Selector:
select when fuse updated_fuel_purchase
Synopsis:
Updates a fuel purchase.
Raises:
none
fuse_trips:delete_fuel_purchase
Selector:
select when fuse unneeded_fuel_purchase
Synopsis:
Deletes the fuel purchase for a given ID
Raises:
none