diff --git a/agency/README.md b/agency/README.md index 5abccedd..34a00393 100644 --- a/agency/README.md +++ b/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 `. The token issuance, expiration and revocation policies are at the discretion of the Agency. @@ -299,3 +310,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 diff --git a/general-information.md b/general-information.md new file mode 100644 index 00000000..c2fe42f9 --- /dev/null +++ b/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) diff --git a/policy/README.md b/policy/README.md index f95dc17f..42a21aca 100644 --- a/policy/README.md +++ b/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: @@ -280,3 +291,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 diff --git a/provider/README.md b/provider/README.md index ccd89dc5..667eb2ad 100644 --- a/provider/README.md +++ b/provider/README.md @@ -21,45 +21,7 @@ Currently, the provider API is implemented for dockless scooter and bikeshare. T `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 @@ -428,6 +390,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