Multiple /vehicles requests at once

[jiffyclub]

Is your feature request related to a problem? Please describe.

In MDS 2, if a vehicle is not present in the /vehicles bulk response it must be requested via /vehicles/{device-id}. If thousands of vehicles need to be requested one at a time this is really time consuming, and this is something that happens to Populus on a regular basis.

Describe the solution you'd like

It would be nice to have a way to query for vehicle information in bulk by supplying multiple device IDs in one request.

Is this a breaking change

It would depend on the implementation.

• I'm not sure

Impacted Spec

For which spec is this feature being requested?

• provider

Describe alternatives you've considered

Additional context

[schnuerle]

I feel like this could be added in MDS 2.1 as a new option for the vehicles endpoint. Would you like to make a PR?

[schnuerle]

Do think this could be a new parameter to send all vehicles via the endpoint? Or maybe a parameter to send only vehicles not present?

[schnuerle]

If you'd like to make a specific suggested solution for this, I can make the PR for MDS 2.1.

[jiffyclub]

I recommend a /vehicles/query POST endpoint that takes a JSON body in the form:

{"device_ids": ["a", "b", "c"]}

• We could recommend a sensible max on the number of IDs like 1000
• Allow pagination in the response

[schnuerle]

I don't think we've done posting of JSON bodies in MDS before, have we?

Even with thousands of vehicles, couldn't you just grab them all the with endpoint, then parse the ones you need? Versus even grabbing 1,000 at a time in pagination?

[jiffyclub]

POST might be unusual in the provider API but I think it's common in the agency API, so it's sort of new but also not. This is sort of a pseudo-POST to take advantage of the JSON body since we aren't asking the API to store anything, only return information.

The MDS spec only requires that the base /vehicles response return vehicles deployed in the last 30 days. We frequently run into the need to get vehicles that are not in the base /vehicles response because they were deployed prior to the most recent 30 days, sometimes thousands of such vehicles. This issue was opened to address this exact case of needing to get info on many, many vehicles that are not in the base /vehicles response.

[schnuerle]

Would love your feedback on this commit based on your needs here!

[jiffyclub]

Looks great! My only thought is that the agency /vehicles POST is something different and if we wanted this bulk query capability in agency as well we'd need it at a different URL, maybe /vehicles/query?

[schnuerle]

Do we need Agency to do this? It seems this feature of sending device IDs to an operator and getting info about them back sits more squarely in the Provider area. That is, there is not a way for an operator to push the details of specific vehicles, without the city specifically asking for them by IDs - and if that's the case they would use this new Provider endpoint.

Or are you saying in Provider we should rename the endpoint to something different, like /vehicles/query?