API Versioning

[black-tea]

Do we want to specify in this spec whether the provider API version should be in a standard location (eg. header vs URL) or leave it up to each provider to determine?

[hunterowens]

Currently, it is AT LEAST required in the response body, as part of JSON API compliance.

see

{
    "version": "x.y.z",
    "data": {
        "trips": [{
            "provider_id": "...",
            "trip_id": "...",
        }]
    }
}

I know some companies have done it in URL vs Header, for now I think we can support either (header OR URL) but would be good to standardize. I think inside the JSON payload is best but open to other options.

[thekaveman]

This is actually spelled out in the JSON Schema - it must come as part of the response, like we show in the README.

I kind of this this isn't an open issue, it's been solved.

[dyakovlev]

Is the question actually "should there be a way to request a specific MDS version from provider endpoints"? API route version identifiers and headers are both ways to do that.

[black-tea]

Perhaps I was getting ahead of myself. How would one "request" a different version?

[black-tea]

@dyakovlev my point exactly 👍

[thekaveman]

Got it, thanks for the clarification @dyakovlev

[dyakovlev]

to save folks the googling, I spent a little time reading about this earlier today. The consensus seems to be "there is no clearly better way, use whatever you've managed to agree to. Avoid getting into arguments about REST semantics with purists".

FWIW, I prefer URI versions, but providers may have different preferences based on their data systems. Reviewing the list of providers, looks like there are already three schemes in flight, so maybe a standard would be beneficial.

[noonhub]

While I normally like to version on the URL, it may make sense to do this as a header. In my case, exposing a new URL to the world is additional overhead, while forking code paths based on a header is less involved.

Given that the spec is evolving quickly and is likely to continue to do so, I can easily see a case when certain agencies and providers are on different versions. If the version is specified an an arbitrary place in the URL then agencies will need to keep track of that, rather than standardizing on a header and a potential error format if the provider does not support the version requested by the header.

I can put together a PR for this in the next day.

[hunterowens]

@noonhub checking in on this PR

[hunterowens]

ref #152.

If we have agency and provider implementation with different versions, it will make sense to have the header implementation of this be done so that if a provider or agency implementation is support 2 or more versions, the requester can ask for the specific version.

[noonhub]

I have actually revised my thinking here. I believe that major versions should be handled in the URL and that a provider should only support a single minor & patch version under each major version at any given time.

Given the semantics of semvar, changing the minor and patch versions under a major versions should not introduce breaking changes and should be fine to move around as the provider wants to.

Thoughts?

[toddapetersen]

I am going to weigh in here. @noonhub, I think the support for a specific version will be more complex than just a version number in the future of Agency. For example, on the technology roadmap, we have considered a "GetParking" endpoint for vehicles... a digital parking product of sorts.
Some cities may or may not want to implement this. Therefor the implemented version will have options that need to be called out so service providers like Uber can call the endpoint to understand which features are turned on/off in a particular jurisdiction. So JSON payload is probably better to handle this complexity. In the future, maybe even a dedicated endpoint to describe features if it becomes complex.

@hunterowens @thekaveman Would like to get your input here.

[noonhub]

It sounds like you are describing an optional endpoint which from the spec's perspective is the same as an optional field or parameter. The spec indicates that it is optional and possibly describes how an implementation should handle if they do not implement that field, parameter, or endpoint. In the case of fields they can be omitted or set to null. Parameters will be ignored or generated an error. Endpoints will produce a 404 NOT FOUND or a 501 NOT IMPLEMENTED.

[thekaveman]

@toddapetersen I see where you are coming from, and definitely agency is going to be a more complex mix of functionality than provider. But I think @noonhub has it right here: this issue addresses the version of MDS at which a list of features are implemented. What you are describing sounds more like enumerating the features a given agency implementation supports/requires.

For example, imagine the GetParking feature was first defined in MDS release 0.3.0, and this endpoint requires the location among other things. Now imagine in MDS release 0.4.0, the location format is altered - adding or removing an optional field for example. This issue talks about where to represent the notion of "here is the version of MDS against which I am (returning | expecting) data".

A change in data format like above is independent of whether or not a given agency implementation supports the GetParking endpoint at all. Different agency implementations may need to support different versions of the location data format, or may not care to enforce parking via MDS.

The "what features does this agency support/require/etc." questions are an important concept to understand and define. Maybe that deserves a separate issue?

[oderby]

Putting up #216 as a proposal for adding this to the specification. In the commit message/PR description I outlined my rationale for proposing staying with versioning via Headers. Looking forward to getting this in.