Merge pull request #437 from populus-ai/clarify-404

Clarify "data does not exist" vs empty data for trips and status changes

Author: schnuerle

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