openmobilityfoundation / openmobilityfoundation/mobility-data-specification
Provider response outside of operating hours
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 746
- Forks
- 252
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 2
Description
Right now, the following is true for the provider /status_changes and /trips endpoints:
For hours in which the provider was not operating the API shall return a
404 Not Foundresponse
However, as a consumer of these endpoints, I've found in practice that it's common for 404 responses to be returned in other situations aside from this one. The most common situation is when data is being requested for a city which doesn't exist or has been removed from the feed, but it also sometimes happens that a bug in the system produces a stray 404 as well.
We want to be able to adjust our ingestion logic when we get these 404 errors, but we can't safely guarantee that we actually are getting the error we think we're getting, which leaves us with the undesirable process of hard-coding checks for each provider's specific and unspecified error messages.
My proposed solution is to define a specific error message string which must also be returned in addition to the 404, something like HOUR NOT IN SERVICE, so that it is completely clear that this is the specific reason that the 404 has been returned.
This would only be a breaking change for providers.
Alternatively the error code could be changed to a less common value (ie, 410, which some operators are already returning under older versions of MDS before this error code was defined). This would be a breaking change for both providers and consumers, so I imagine it is less preferable.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Begin with the provider /status_changes and /trips endpoint contract described in the issue. Review how these endpoints currently distinguish outside operating hours from other 404 cases, then determine and document one response convention that providers and consumers can consistently recognize. Done means the selected behavior and its compatibility impact are clearly specified.
Written by the indexing model from the issue text.
Assessment
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100