OPTIONS for version negotiation

[billdirks]

Explain pull request
Please provide a clear and concise reason for this pull request and the impact of the change

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).

[ X ] Yes, breaking*
[ ] No, not breaking
[ ] I'm not sure

*The old endpoints work identically. This PR adds a new versions endpoint.

Provider or agency
Which API(s) will this pull request impact:
[ X ] provider
[ ] agency
[ ] both

Additional context

During the weekly provider MDS meeting on 4/4/2019 Jascha, @jfh01, asked me to put together a PR for a versions endpoint. In addition to updating the README, I've made a JSON schema for this endpoint, generated the JSON schema using generate_provider_schema.py, and validated as follows:

import json
import jsonschema

# load generated schema assuming in base directory of repo
with  open("provider/versions.json") as f:
    s = json.load(f)

# succeeds
j = {"version": "0.3.0", "data": {"versions": ["0.2", "0.3"]}}
jsonschema.validate(j, s)

# fails additional properties as top level key
j = {"version": "0.3.0", "data": {"versions": ["0.2", "0.3"]}, "other": "stuff"}
jsonschema.validate(j, s)

# fails additional properties inside data
j = {"version": "0.3.0", "data": {"versions": ["0.2", "0.3"], "other": "stuff"}}
jsonschema.validate(j, s)

# fails validating "0.3.4"
j = {"version": "0.3.0", "data": {"versions": ["0.2", "0.3.4"]}}
jsonschema.validate(j, s)

Comments and feedback appreciated!

[dyakovlev]

it's probably worth documenting somewhere about the rationale of trimming these to minor version only.

[billdirks]

I've updated this do the negotiation using the OPTIONS method and am now returning the whole string a client would use in the request ACCEPT header. It is now made explicit in the README.md file.

[ccolgrove]

@billdirks - we'd talked about on the call switching this over to an OPTIONS request. Have you had a chance to look into that?

[lionel-panhaleux]

To summarize discussion from 4/11 & 4/18 and give a little bit more detail on the possible implementation using OPTIONS:

• The specification states that a specific Content-Type should be used for responses, cf. https://github.com/CityOfLosAngeles/mobility-data-specification/tree/dev/provider#versioning

This means an OPTIONS request can be used for version negotiation using the Accept header, cf. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept . Example:

Ask for options, stating that version 0.2 is preferred to version 0.3 (using the q parameter):

OPTIONS /trips/ HTTP/1.1 
Host: provider.example.com 
Accept: application/vnd.mds.provider+json;version=0.2,application/vnd.mds.provider+json;version=0.3;q=0.9

Answer: Only version 0.3 available

HTTP/1.1 200 OK
Content-Type: mds.provider+json;version=0.3

This allows version negotiation without changing the specification. A PR for some added precisions (in readme and/or JSON spec) could be good, if anyone feels up to it. @billdirks would this fit your need ?

[billdirks]

Thank you for the feedback! I've updated the README to explicitly describe how the OPTIONS method (initially suggested @dyakovlev, I believe) could be used to negotiate versions and have integrated @lionel-panhaleux's comment.

[yoimnik]

i feel that this overcomplicates the versioning of the MDS Provider spec at a very early stage.

my understanding of OPTIONS is that historically it's typically been used by browsers to specify a variety of document formats in order for better browser rendering of content. in the case of MDS, i think it's very clear that when we publish a new version, we want to deprecate the old, and in order to encourage the deprecation of the old to be done in a timely manner, we shouldn't allow negotiations for older versions after a short amount of time passes the release of a major version.

right now, clients interface with the MDS Providers API either through their own software or using MDS Provider Services, and in either case I don't see a need to do content negotiation -- either the client-side software is ready to accept an updated version of MDS, or it will use an older version of MDS.

if a client can accept an updated version of MDS Provider, i don't see a case where they would want to accept the older version, which would happen via OPTIONS content negotiation

my perspective on this may be missing some things here, but i don't see much value in including this in the spec.