Add versioning for Agency and Policy API (#444)

* add versioning for Agency API

A minimal set of changes to add versioning to the Agency API and stay consistent with the Provider API.

* add backward-compatibility support

* Fix table of content link

* Create general-information.md

This commit just copies the Versioning section from the provider spec to a "General information" file.

* Agency : reference general information versioning

* Provider: reference general information versioning

* Policy: reference general information versioning

* Correct fallback provider version

Author: Retzoh

agency/README.md

@@ -7,6 +7,7 @@ This specification contains a collection of RESTful APIs used to specify the dig
 
 ## Table of Contents
 
+* [General Information](#general-information)
 * [Authorization](#authorization)
 * [Timestamps](#timestamps)
 * [Vehicles](#vehicles)
@@ -18,6 +19,16 @@ This specification contains a collection of RESTful APIs used to specify the dig
 * [Enum definitions](#enum-definitions)
 * [Responses](#responses)
 
+## General information
+
+The following information applies to all `agency` API endpoints. Details on providing authorization to endpoints is specified in the [Authorization](#authorization) section.
+
+### Versioning
+
+`agency` APIs must handle requests for specific versions of the specification from clients.
+
+Versioning must be implemented as specified in the [`General information versioning section`][general-information/versioning].
+
 ## Authorization
 
 When making requests, the Agency API expects `provider_id` to be part of the claims in a [JWT](https://jwt.io/)  `access_token` in the `Authorization` header, in the form `Authorization: Bearer <access_token>`. The token issuance, expiration and revocation policies are at the discretion of the Agency.
@@ -300,3 +311,8 @@ A vehicle may have one or more values from the `propulsion`, depending on the nu
 | `error`             | String   | Error message string   |
 | `error_description` | String   | Human readable error description (can be localized) |
 | `error_details`     | String[] | Array of error details |
+
+[Top][toc]
+
+[toc]: #table-of-contents
+[general-information/versioning]: /general-information.md#versioning

general-information.md

@@ -0,0 +1,48 @@
+# Mobility Data Specification: **General information**
+
+This document contains specifications that are shared between the various MDS APIs such as `agency`, `provider` and `policy`.
+
+## Table of Contents
+
+* [Versioning](#versioning)
+
+## Versioning
+
+MDS APIs must handle requests for specific versions of the specification from clients.
+
+Versioning must be implemented through the use of a custom media-type, `application/vnd.mds.provider+json`, combined with a required `version` parameter.
+
+The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `0.2.1` would be specified as `application/vnd.mds.provider+json;version=0.2`
+
+> Note: Normally breaking changes are covered by different major versions in semver notation. However, as this specification is still pre-1.0.0, changes in minor versions may include breaking changes, and therefore are included in the version string.
+
+Clients must specify the version they are targeting through the `Accept` header. For example:
+
+```http
+Accept: application/vnd.mds.provider+json;version=0.3
+```
+
+> Since versioning was not available from the start, the following APIs provide a fallback version if the `Accept` header is not set as specified above:
+> - The `provider` API must respond as if version `0.2` was requested.
+> - The `agency` API must respond as if version `0.3` was requested.
+> - The `policy` API must respond as if version `0.4` was requested.
+
+If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. If this occurs, a client can explicitly negotiate available versions.
+
+A client negotiates available versions using the `OPTIONS` method to an MDS endpoint. For example, to check if `trips` supports either version `0.2` or `0.3` with a preference for `0.2`, the client would issue the following request:
+
+```http
+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
+```
+
+The response will include the most preferred supported version in the `Content-Type` header. For example, if only `0.3` is supported:
+
+```http
+Content-Type: application/vnd.mds.provider+json;version=0.3
+```
+
+The client can use the returned value verbatim as a version request in the `Accept` header.
+
+[Top](#table-of-contents)

policy/README.md

@@ -4,12 +4,23 @@ This specification describes the digital relationship between _mobility as a ser
 
 ## Table of Contents
 
+- [General Information](#general-information)
 - [Background](#background)
 - [Distribution](#distribution)
   - [REST Endpoints](#rest-endpoints)
   - [Flat Files](#flat-files)
 - [Schema](#schema)
 
+## General information
+
+The following information applies to all `policy` API endpoints.
+
+### Versioning
+
+`policy` APIs must handle requests for specific versions of the specification from clients.
+
+Versioning must be implemented as specified in the [`General information versioning section`][general-information/versioning].
+
 ## Background
 
 The goal of this specification is to enable Agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both _mobility as a service_ Providers and riders / users. Examples of policies include:
@@ -281,3 +292,5 @@ If a vehicle is matched with a rule, then it _will not_ be considered in the sub
 The internal mechanics of ordering are up to the Policy editing and hosting software.
 
 [Top](#table-of-contents)
+
+[general-information/versioning]: /general-information.md#versioning

provider/README.md

@@ -21,45 +21,7 @@ Currently, the provider API is implemented for shared dockless scooters, bikes,
 
 `provider` APIs must handle requests for specific versions of the specification from clients.
 
-Versioning must be implemented through the use of a custom media-type, `application/vnd.mds.provider+json`, combined with a required `version` parameter.
-
-The version parameter specifies the dot-separated combination of major and minor versions from a published version of the specification. For example, the media-type for version `0.2.1` would be specified as `application/vnd.mds.provider+json;version=0.2`
-
-> Note: Normally breaking changes are covered by different major versions in semver notation. However, as this specification is still pre-1.0.0, changes in minor versions may include breaking changes, and therefore are included in the version string.
-
-Clients must specify the version they are targeting through the `Accept` header. For example:
-
-```http
-Accept: application/vnd.mds.provider+json;version=0.3
-```
-
-> Since versioning was not added until the 0.3.0 release, if the `Accept` header is not set as specified above, the `provider` API must respond as if version `0.2` was requested.
-
-Responses to client requests must indicate the version the response adheres to through the `Content-Type` header. For example:
-
-```http
-Content-Type: application/vnd.mds.provider+json;version=0.3
-```
-
-> Since versioning was not added until the 0.3.0 release, if the `Content-Type` header is not set as specified above, version `0.2` must be assumed.
-
-If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. If this occurs, a client can explicitly negotiate available versions.
-
-A client negotiates available versions using the `OPTIONS` method to an MDS endpoint. For example, to check if `trips` supports either version `0.2` or `0.3` with a preference for `0.2`, the client would issue the following request:
-
-```http
-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
-```
-
-The response will include the most preferred supported version in the `Content-Type` header. For example, if only `0.3` is supported:
-
-```http
-Content-Type: application/vnd.mds.provider+json;version=0.3
-```
-
-The client can use the returned value verbatim as a version request in the `Accept` header.
+Versioning must be implemented as specified in the [`General information versioning section`][general-information/versioning].
 
 ### Response Format
 
@@ -432,6 +394,7 @@ Should either side of the requested time range be greater than 2 weeks before th
 
 [Top][toc]
 
+[general-information/versioning]: /general-information.md#versioning
 [geo]: #geographic-data
 [sc-schema]: status_changes.json
 [status]: #status-changes