Clarify Provider API responses

The trips and status changes endpoints are expected to return
HTTP 404 responses when data "does not exist". I'm trying to
clarify that that means the future and hours when the provider
was not in operation in the municipality. For past hours during
which the provider was operating but nothing happened they should
return "200 OK" responses with  empty arrays of trips or status
changes. Additionally, for hours that are not available in the API
because the data is still be processed the API shall return a
"102 Processing" response to indicate the requester should check back
later.

Author: jiffyclub

provider/README.md

@@ -185,14 +185,33 @@ The `/trips` API should allow querying trips with the following query parameters
 | --------------- | ------ | --------------- |
 | `end_time` | `YYYY-MM-DDTHH`, an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) extended datetime representing an UTC hour between 00 and 23. | All trips with an end time occurring within the hour. For example, requesting `end_time=2019-10-01T07` returns all trips where `2019-10-01T07:00:00 <= trip.end_time < 2019-10-01T08:00:00` UTC. |
 
-If the provider was operational during the requested hour the provider shall return
-a 200 response, even if there are no trips to report (in which case
-the response will contain an empty list of trips).
-If the requested hour occurs in a time period in which the provider was not operational
-or the hour is not yet in the past `/trips` shall return a `404 Not Found` error.
-
 Without an `end_time` query parameter, `/trips` shall return a `400 Bad Request` error.
 
+### Trips - Responses
+
+The API's response will depend on the hour queried and the status of data
+processing for that hour:
+
+* For hours that are not yet in the past the API shall return a `404 Not Found`
+  response.
+* For hours in which the provider was not operating the API shall return a
+  `404 Not Found` response.
+* For hours that are in the past but for which data is not yet available
+  the API shall return a `102 Processing` response.
+* For all other hours the API shall return a `200 OK` response with a fully
+  populated body, even for hours that contain no trips to report.
+  If the hour has no trips to report the response shall contain an empty
+  array of trips:
+  
+    ```json
+    {
+        "version": "x.y.z",
+        "data": {
+            "trips": []
+        }
+    }
+    ```
+
 For the near-ish real time use cases, please use the [events][events] endpoint.
 
 [Top][toc]
@@ -287,14 +306,33 @@ The `/status_changes` API should allow querying status changes with the followin
 | --------------- | ------ | --------------- |
 | `event_time` | `YYYY-MM-DDTHH`, an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) extended datetime representing an UTC hour between 00 and 23. | All status changes with an event time occurring within the hour. For example, requesting `event_time=2019-10-01T07` returns all status changes where `2019-10-01T07:00:00 <= status_change.event_time < 2019-10-01T08:00:00` UTC. |
 
-If the provider was operational during the requested hour the provider shall return
-a 200 response, even if there are no status changes to report (in which case
-the response will contain an empty list of status changes).
-If the requested hour occurs in a time period in which the provider was not operational
-or the hour is not yet in the past `/status_changes` shall return a `404 Not Found` error.
-
 Without an `event_time` query parameter, `/status_changes` shall return a `400 Bad Request` error.
 
+### Status Changes - Responses
+
+The API's response will depend on the hour queried and the status of data
+processing for that hour:
+
+* For hours that are not yet in the past the API shall return a `404 Not Found`
+  response.
+* For hours in which the provider was not operating the API shall return a
+  `404 Not Found` response.
+* For hours that are in the past but for which data is not yet available
+  the API shall return a `102 Processing` response.
+* For all other hours the API shall return a `200 OK` response with a fully
+  populated body, even for hours that contain no status changes to report.
+  If the hour has no status changes to report the response shall contain an
+  empty array of status changes:
+  
+    ```json
+    {
+        "version": "x.y.z",
+        "data": {
+            "status_changes": []
+        }
+    }
+    ```
+
 [Top][toc]
 
 ## Reports