Add versions endpoint.

Author: bill dirks

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

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
+}

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

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
+}