Update version negotiation to use OPTIONS method

Author: bill dirks

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

generate_schema/provider/versions.json

@@ -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