Clarification on Agency Telemetry endpoint error behavior

[nheilbuth]

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

In https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency#vehicle---telemetry it is described that the endpoint returns 200 response containing the number of total records, number of successful records and an array of failed records. It also decribes 4 different 400 responses, but it doesnt describe when a 200 containing failures should be used versus returning a 400. Also it is unclear which 400 should be used if the list of failures has mixed reasons (ie. some missing a param and others having unregistered vehicles).

Describe the solution you'd like

Add clearification on when to return 200 containing failed records and when to return 400. Also add clearification on which 400 to use when failures has mixed reasons

Is this a breaking change

A breaking change would require consumers or implementors of the API to modify their code for it to continue to function (ex: renaming of a required field or the change in data type of an existing field). A non-breaking change would allow existing code to continue to function (ex: addition of an optional field or the creation of a new optional endpoint).

• Yes, breaking

Impacted Spec

For which spec is this feature being requested?

• agency

Describe alternatives you've considered

1. Have the endpoint return 400 when one or more records fail. The type of 400 is still unclear if more than one fail, for different reasonse
2. Return 400 when all records fail. The type of 400 is still unclear if more than one fail, for different reasonse
3. Change the 200 response failures array to be an array of error responses, instead of just the failed records them self.

Additional context

The current failures array of the 200 response doesn't tell anything about why the records in the array failed.

[schnuerle]

If you'd like to make a pull request for this clarification, please do. We can consider it for the next release 2.0 since it will be a major release and allow breaking changes.

[nheilbuth]

Correct me if I'm wrong, but making a PR for 2.0 on this doesnt seem to make much sense. It looks like the Telemetry endpoint has been removed entirely from 2.0!

[schnuerle]

Telemetry is still there in the latest release, 1.2:

• https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency#telemetry-data
• https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency#vehicle---telemetry

2.0 is in the start of development now, and we haven't removed telemetry. Where do you see it removed?

[nheilbuth]

@schnuerle I look at the current 2.x branch: https://github.com/openmobilityfoundation/mobility-data-specification/tree/0.2.x/agency There is indeed a Telemetry object, but no batch telemetry endpoint. This issue is regarding error responses from the batch telemetry endpoint. My understanding from looking at the 2.x branch, was that the endpoint structure had been changed and it would no longer support batch telemetry!? So you are saying that the batch telemetry endpoint might be included in 2.x? I can make a PR, but it will be agains the main branch and not 2.x, as the complete definition of a telemetry batch endpoint in 2.x seems out of scope of this issue.

[schnuerle]

Maybe I'm misunderstanding, but the link you posted was for version 0.2 (Oct 01, 2018) https://github.com/openmobilityfoundation/mobility-data-specification/tree/0.2.x/agency

not 1.2 (the latest release Nov 04, 2021) https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-1.2.0/agency or https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/agency

There hasn't been much work done on 2.0 yet, but you can see the plan here: https://github.com/openmobilityfoundation/governance/wiki/Release-2.0.0

See all releases here: https://github.com/openmobilityfoundation/mobility-data-specification/releases

[nheilbuth]

@schnuerle ARGH I'm so sorry, thats my bad. Guess I got confused by your comment that you would consider it for 2.0 and I must have missed the 0. in front of the branch name :(

I will make a PR with my suggestions.

Again sorry about the confusion

[schnuerle]

Resolved with #740