Skip to content

Clarify which vehicles to include in the /vehicles endpoint #882

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
schnuerle merged 2 commits into from
Dec 13, 2023
Merged

Clarify which vehicles to include in the /vehicles endpoint #882

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5f5e98e
Update provider vehicles endpoints descriptions
jiffyclub Oct 18, 2023
90ad321
Update /vehicles endpoint description
jiffyclub Dec 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions provider/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,22 +168,19 @@ For Timestamps, Vehicle Types, Propulsion Types, UUIDs, Costs, and Currencies, r

## Vehicles

The `/vehicles` is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [`vehicle_state`][vehicle-states] should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere` and `removed` which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these must only persist in the feed for 90 minutes before being removed.
There are two vehicles related endpoints:

As with other MDS APIs, `/vehicles` is intended for use by regulators, not by the general public. `/vehicles` can be deployed by providers as a standalone MDS endpoint for agencies without requiring the use of other endpoints, due to the [modularity](/README.md#modularity) of MDS. See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for how this compares to GBFS `/free_bike_status`. Note that using authenticated `/vehicles` does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both `/vehicles` and GBFS endpoints, the `/vehicles` endpoint should be considered source of truth regarding an agency's compliance checks.
- `/vehicles` returns unchanging information about vehicles such as vehicle and propulsion type
- `/vehicles/status` returns the current status of vehicles for real-time monitoring

In addition to the standard [Provider payload wrapper](#response-format), responses from this endpoint should contain the last update timestamp and amount of time until the next update in accordance with the [Data Latency Requirements][data-latency]:
As with other MDS APIs, the vehicles endpoints are intended for use by regulators, not by the general public. They can be deployed by providers as standalone MDS endpoints for agencies without requiring the use of other endpoints, due to the [modularity](/README.md#modularity) of MDS. See our [MDS Vehicles Guide](https://github.com/openmobilityfoundation/mobility-data-specification/wiki/MDS-Vehicles) for how this compares to GBFS `/free_bike_status`. Note that using authenticated vehicles endpoints does not replace the role of a public [GBFS][gbfs] feed in enabling consumer-facing applications. If a provider is using both the vehicles endpoints and GBFS endpoints, the vehicles endpoints should be considered source of truth regarding an agency's compliance checks.

```json
{
"version": "x.y.z",
"last_updated": "12345",
"ttl": "12345",
"vehicles": []
}
```
### Vehicle Information

The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Contains vehicle properties that do not change often.
The `/vehicles` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles.
It contains vehicle properties that do not change often.
When `/vehicles` is called without specifying a device ID it should return every vehicle that has
ever been deployed in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility.

**Endpoint:** `/vehicles/{device_id}`
**Method:** `GET`
Expand Down Expand Up @@ -228,7 +225,21 @@ See [Responses][responses], [Bulk Responses][bulk-responses], and [schema][schem

### Vehicle Status

The `/vehicles/status` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles. Contains specific vehicle status records that are updated frequently.
The `/vehicles/status` endpoint is a near-realtime endpoint and returns the current status of vehicles in an agency's [Jurisdiction](/general-information.md#definitions) and/or area of agency responsibility. All vehicles that are currently in any [PROW](/general-information.md#definitions) state [`vehicle_state`][vehicle-states] should be returned in this payload. Since all states are returned, care should be taken to filter out states not in the [PROW](/general-information.md#definitions) if doing vehicle counts. For the states `elsewhere`, `removed`, and `missing`, which include vehicles not in the [PROW](/general-information.md#definitions) but provide some operational clarity for agencies, these vehicles must only persist in the feed for 90 minutes before being removed (and should persist in the feed for at least 90 minutes).
Copy link
Contributor

@wellorder wellorder Dec 6, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"these vehicles must only persist in the feed for 90 minutes before being removed (and should persist in the feed for at least 90 minutes)" is the same as "these vehicles must persist in the feed for exactly 90 minutes", which sounds a bit strict, honestly. (I suppose the existing language comes across this way as well, but less explicitly.)

I really don't want to be called out-of-compliance because a vehicle was present for 91 minutes because some backend process got delayed by 1 minute. Technically enforcing such a TTL is not much more difficult than one with a grace period, but maybe allowing for things to be present for, say, up to 120 minutes will save some annoying discussions. I can't imagine what logic a consumer might have that would be thrown off by such a grace period (maybe someone will think of something though).

Copy link
Contributor

@wellorder wellorder Dec 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We didn't come to a final decision on this in the meeting today, but people seemed open to softening this language a bit. Is "these vehicles must persist for no more than 90 minutes" the spirit of the original language?

I'll also mention that we do not currently return elsewhere vehicles at all (they're not in whichever jurisdiction, so returning "the status of all vehicles currently in the jurisdiction" would seem to naturally exclude them, the elsewhere update would be available in events/recent if people want to see those in near-realtime), so a minimum guarantee for persisting such vehicles would be a change.


The `/vehicles/status` endpoint returns the specified vehicle (if a device_id is provided) or a list of known vehicles.
It contains specific vehicle status records that are updated frequently.

In addition to the standard [Provider payload wrapper](#response-format), responses from this endpoint should contain the last update timestamp and amount of time until the next update in accordance with the [Data Latency Requirements][data-latency]:

```json
{
"version": "x.y.z",
"last_updated": "12345",
"ttl": "12345",
"vehicles": []
}
```

**Endpoint:** `/vehicles/status/{device_id}`
**Method:** `GET`
Expand Down