Skip to content

Commit

Permalink
Clarify trips and status changes response behavior
Browse files Browse the repository at this point in the history
In MDS 0.4.x we request trips and status changes for a given hour.
A provider may have no data to report for the requested hour
multiple reasons, including:

- The hour has not yet fully passed
- The provider was not operational in the region during the hour
- The provider has not yet completed processing that hour's data
- No trips or events occurred during the hour

Differentiating the last two reasons is particularly important because
it lets consumers of APIs know whether or not they need to re-request
the hour at a later time. A successful 200 response with an empty
list of data clearly communicates that the provider has nothing to
report for that hour and that it's not necessary to try again later.
Having this behavior consistent across providers would help us at
Populus spend less time requesting data and reduce the number of
requests received by providers.
  • Loading branch information
jiffyclub committed Nov 5, 2020
1 parent b6d9ea5 commit b07bb80
Showing 1 changed file with 10 additions and 2 deletions.
12 changes: 10 additions & 2 deletions provider/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,11 @@ 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 data does not exist or the hour has not completed, `/trips` shall return a `404 Not Found` error.
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.

Expand Down Expand Up @@ -276,7 +280,11 @@ 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 data does not exist or the hour has not completed, `/status_changes` shall return a `404 Not Found` error.
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.

Expand Down

0 comments on commit b07bb80

Please sign in to comment.