From 476eac8a6a93cc465fc5a86d3e0974e02f14c323 Mon Sep 17 00:00:00 2001 From: bill dirks Date: Tue, 9 Apr 2019 16:29:42 -0700 Subject: [PATCH 1/2] Add versions endpoint. --- generate_schema/generate_provider_schema.py | 14 ++++++++ generate_schema/provider/versions.json | 39 +++++++++++++++++++++ provider/README.md | 18 ++++++++++ provider/versions.json | 39 +++++++++++++++++++++ 4 files changed, 110 insertions(+) create mode 100644 generate_schema/provider/versions.json create mode 100644 provider/versions.json diff --git a/generate_schema/generate_provider_schema.py b/generate_schema/generate_provider_schema.py index 6ae91d1e..39150f68 100644 --- a/generate_schema/generate_provider_schema.py +++ b/generate_schema/generate_provider_schema.py @@ -157,3 +157,17 @@ def get_json_file(path): # Write to the `provider` directory. with open("../provider/status_changes.json", "w") as statusfile: statusfile.write(json.dumps(status_changes, indent=2)) + + # Create the standalone version JSON schema by including the needed definitions + versions = get_json_file("provider/versions.json") + versions["definitions"] = { + "links": common["definitions"]["links"], + "version": common["definitions"]["version"], + } + + # Check that it is a valid schema + jsonschema.Draft6Validator.check_schema(versions) + # Write to the `provider` directory. + with open("../provider/versions.json", "w") as f: + f.write(json.dumps(versions, indent=2)) + diff --git a/generate_schema/provider/versions.json b/generate_schema/provider/versions.json new file mode 100644 index 00000000..5fdaeb3e --- /dev/null +++ b/generate_schema/provider/versions.json @@ -0,0 +1,39 @@ +{ + "$id": "https://raw.githubusercontent.com/CityofLosAngeles/mobility-data-specification/master/provider/versions.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Provider Schema, versions payload", + "type": "object", + "definitions": {}, + "required": [ + "data" + ], + "properties": { + "version": { + "$ref": "#/definitions/version" + }, + "data": { + "$id": "#/properties/data", + "type": "object", + "title": "The page of data", + "required": [ + "versions" + ], + "properties": { + "versions": { + "$id": "#/properties/data/properties/versions", + "type": "array", + "title": "The versions Schema", + "items": { + "type": "string", + "pattern": "^0\\.[0-9]$" + } + } + }, + "additionalProperties": false + }, + "links": { + "$ref": "#/definitions/links" + } + }, + "additionalProperties": false +} diff --git a/provider/README.md b/provider/README.md index 7373c29f..056bfb0d 100644 --- a/provider/README.md +++ b/provider/README.md @@ -7,6 +7,7 @@ This specification contains a data standard for *mobility as a service* provider * [General Information](#general-information) * [Trips](#trips) * [Status Changes](#status-changes) +* [Versions](#versions) * [Realtime Data](#realtime-data) ## General Information @@ -302,6 +303,22 @@ When multiple query parameters are specified, they should all apply to the retur | | | `rebalance_pick_up` | Device removed from street and will be placed at another location to rebalance service | | | | `maintenance_pick_up` | Device removed from street so it can be worked on | +[Top][toc] + +## Versions + +The versions endpoint allows user to query for the versions the provider supports. + +Endpoint: `/versions` +Method: `GET` +Schema: [`versions` schema][versions-schema] +`data` Payload: `{ "versions": [] }`, an array of version strings usable in versioned requests + +Here is an example payload: + + "versions": [ "0.2", "0.3" ] + + [Top][toc] ## Realtime Data @@ -320,3 +337,4 @@ All MDS compatible `provider` APIs must expose a public [GBFS](https://github.co [toc]: #table-of-contents [trips-schema]: trips.json [ts]: #timestamps +[versions-schema] versions.json diff --git a/provider/versions.json b/provider/versions.json new file mode 100644 index 00000000..5fdaeb3e --- /dev/null +++ b/provider/versions.json @@ -0,0 +1,39 @@ +{ + "$id": "https://raw.githubusercontent.com/CityofLosAngeles/mobility-data-specification/master/provider/versions.json", + "$schema": "http://json-schema.org/draft-06/schema#", + "title": "The MDS Provider Schema, versions payload", + "type": "object", + "definitions": {}, + "required": [ + "data" + ], + "properties": { + "version": { + "$ref": "#/definitions/version" + }, + "data": { + "$id": "#/properties/data", + "type": "object", + "title": "The page of data", + "required": [ + "versions" + ], + "properties": { + "versions": { + "$id": "#/properties/data/properties/versions", + "type": "array", + "title": "The versions Schema", + "items": { + "type": "string", + "pattern": "^0\\.[0-9]$" + } + } + }, + "additionalProperties": false + }, + "links": { + "$ref": "#/definitions/links" + } + }, + "additionalProperties": false +} From 56f5fa1ed1a6f011cf91bc670e71ecdb0476c8d1 Mon Sep 17 00:00:00 2001 From: bill dirks Date: Fri, 26 Apr 2019 12:10:05 -0700 Subject: [PATCH 2/2] Update version negotiation to use OPTIONS method --- generate_schema/generate_provider_schema.py | 14 -------- generate_schema/provider/versions.json | 39 --------------------- provider/README.md | 34 +++++++++--------- provider/versions.json | 39 --------------------- 4 files changed, 16 insertions(+), 110 deletions(-) delete mode 100644 generate_schema/provider/versions.json delete mode 100644 provider/versions.json diff --git a/generate_schema/generate_provider_schema.py b/generate_schema/generate_provider_schema.py index 39150f68..6ae91d1e 100644 --- a/generate_schema/generate_provider_schema.py +++ b/generate_schema/generate_provider_schema.py @@ -157,17 +157,3 @@ def get_json_file(path): # Write to the `provider` directory. with open("../provider/status_changes.json", "w") as statusfile: statusfile.write(json.dumps(status_changes, indent=2)) - - # Create the standalone version JSON schema by including the needed definitions - versions = get_json_file("provider/versions.json") - versions["definitions"] = { - "links": common["definitions"]["links"], - "version": common["definitions"]["version"], - } - - # Check that it is a valid schema - jsonschema.Draft6Validator.check_schema(versions) - # Write to the `provider` directory. - with open("../provider/versions.json", "w") as f: - f.write(json.dumps(versions, indent=2)) - diff --git a/generate_schema/provider/versions.json b/generate_schema/provider/versions.json deleted file mode 100644 index 5fdaeb3e..00000000 --- a/generate_schema/provider/versions.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "$id": "https://raw.githubusercontent.com/CityofLosAngeles/mobility-data-specification/master/provider/versions.json", - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "The MDS Provider Schema, versions payload", - "type": "object", - "definitions": {}, - "required": [ - "data" - ], - "properties": { - "version": { - "$ref": "#/definitions/version" - }, - "data": { - "$id": "#/properties/data", - "type": "object", - "title": "The page of data", - "required": [ - "versions" - ], - "properties": { - "versions": { - "$id": "#/properties/data/properties/versions", - "type": "array", - "title": "The versions Schema", - "items": { - "type": "string", - "pattern": "^0\\.[0-9]$" - } - } - }, - "additionalProperties": false - }, - "links": { - "$ref": "#/definitions/links" - } - }, - "additionalProperties": false -} diff --git a/provider/README.md b/provider/README.md index 056bfb0d..9eb1273a 100644 --- a/provider/README.md +++ b/provider/README.md @@ -7,7 +7,6 @@ This specification contains a data standard for *mobility as a service* provider * [General Information](#general-information) * [Trips](#trips) * [Status Changes](#status-changes) -* [Versions](#versions) * [Realtime Data](#realtime-data) ## General Information @@ -42,6 +41,22 @@ Content-Type: application/vnd.mds.provider+json;version=0.3 If an unsupported or invalid version is requested, the API must respond with a status of `406 Not Acceptable`. In which case, the response should include a body specifying a list of supported versions. +A client can explicitly negotiate headers 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. + ### Response Format The response to a client request must include a valid HTTP status code defined in the [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml). It also must set the `Content-Type` header, as specified in the [Versioning](#Versioning) section. @@ -303,22 +318,6 @@ When multiple query parameters are specified, they should all apply to the retur | | | `rebalance_pick_up` | Device removed from street and will be placed at another location to rebalance service | | | | `maintenance_pick_up` | Device removed from street so it can be worked on | -[Top][toc] - -## Versions - -The versions endpoint allows user to query for the versions the provider supports. - -Endpoint: `/versions` -Method: `GET` -Schema: [`versions` schema][versions-schema] -`data` Payload: `{ "versions": [] }`, an array of version strings usable in versioned requests - -Here is an example payload: - - "versions": [ "0.2", "0.3" ] - - [Top][toc] ## Realtime Data @@ -337,4 +336,3 @@ All MDS compatible `provider` APIs must expose a public [GBFS](https://github.co [toc]: #table-of-contents [trips-schema]: trips.json [ts]: #timestamps -[versions-schema] versions.json diff --git a/provider/versions.json b/provider/versions.json deleted file mode 100644 index 5fdaeb3e..00000000 --- a/provider/versions.json +++ /dev/null @@ -1,39 +0,0 @@ -{ - "$id": "https://raw.githubusercontent.com/CityofLosAngeles/mobility-data-specification/master/provider/versions.json", - "$schema": "http://json-schema.org/draft-06/schema#", - "title": "The MDS Provider Schema, versions payload", - "type": "object", - "definitions": {}, - "required": [ - "data" - ], - "properties": { - "version": { - "$ref": "#/definitions/version" - }, - "data": { - "$id": "#/properties/data", - "type": "object", - "title": "The page of data", - "required": [ - "versions" - ], - "properties": { - "versions": { - "$id": "#/properties/data/properties/versions", - "type": "array", - "title": "The versions Schema", - "items": { - "type": "string", - "pattern": "^0\\.[0-9]$" - } - } - }, - "additionalProperties": false - }, - "links": { - "$ref": "#/definitions/links" - } - }, - "additionalProperties": false -}