Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add versioning requirement to Provider API #216

Merged

Conversation

oderby
Copy link
Contributor

@oderby oderby commented Feb 1, 2019

provider APIs must support versioning going forward. As implemented
here, we will use a custom media-type to negotiate the API version a client
and server will use. A couple reasons for taking this approach:

  • API versioning will become important as 0.3.0 and future releases are
    published with breaking changes that Providers, cities and third-parties
    will need to implement/adopt on differing timelines.
  • Because this is a specification for others (Providers) to implement
    their APIs against, mandating URI structure beyond endpoints could be
    burdensome or limiting. Conversely, leveraging standard HTTP Headers in
    a compliant manner places no limitations.
  • Further, in practice, many providers have already begun implementing
    their own versioning in their registered mds_api_url.

Closes #114

`provider` APIs must support versioning going forward. As implemented
here, we will use a custom media-type to negotiate the API version a client
and server will use. A couple reasons for taking this approach:
* API versioning will become important as 0.3.0 and future releases are
  published with breaking changes that Providers, cities and third-parties
  will need to implement/adopt on differing timelines.
* Because this is a specification for others (Providers) to implement
  their APIs against, mandating URI structure beyond endpoints could be
  burdensome or limiting. Conversely, leveraging standard HTTP Headers in
  a compliant manner places no limitations.
* Further, in practice, many providers have already begun implementing
  their own versioning in their registered `mds_api_url`.

Closes openmobilityfoundation#114
@oderby
Copy link
Contributor Author

oderby commented Feb 1, 2019

I have a tendency to be verbose, and this reads as a bit more verbose than the rest of the spec, so happy to hear suggestions for making it more terse, in addition to general comments. Thanks!

@oderby oderby mentioned this pull request Feb 1, 2019
@oderby
Copy link
Contributor Author

oderby commented Feb 1, 2019

Also, I didn't see any obvious way this needed could be tied into https://github.com/CityOfLosAngeles/mobility-data-specification/blob/dev/ReleaseGuidelines.md or the JSON schema, but let me know if I missed something.

@hunterowens hunterowens added this to the 0.3.0 milestone Feb 3, 2019
@hunterowens
Copy link
Collaborator

hunterowens commented Feb 4, 2019

I think headers should be the way to go, give that I don't want to touch endpoints URIs expect for the names.

If a provider feels like it, they could probably configure redirects to redirect requests from {mds_api_url}/{endpoint} with header: {some_version_number} to /{some_version_number}/{endpoint} in order to keep codebases as clean as possible.

Going to approve for now but pinging @noonhub for thoughts before I merge.

@hunterowens hunterowens merged commit 5cb3f4e into openmobilityfoundation:dev Feb 6, 2019
@oderby oderby deleted the add-provider-versioning branch February 6, 2019 18:15
@hunterowens hunterowens mentioned this pull request Feb 14, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants