Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DRAFT] Add trips to agency #27

Draft
wants to merge 2 commits into
base: dev
Choose a base branch
from
Draft

[DRAFT] Add trips to agency #27

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ac3d61
firt draft of /trips in Agency
marie-x May 3, 2021
6e10f53
add error responses for POST
marie-x May 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions agency/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,7 @@ _No content returned if no vehicle matching `device_id` is found._
The vehicle `/event` endpoint allows the Provider to control the state of the vehicle including deregister a vehicle from the fleet.

Endpoint: `/vehicles/{device_id}/event`

Method: `POST`

Path Params:
Expand Down Expand Up @@ -259,6 +260,56 @@ A standard point of vehicle telemetry. References to latitude and longitude impl

[Top][toc]

## Trips

The `/trips` endpoint is a subset of the similar endpoint in Provider, except it's push instead of pull. It receives trip information that is above and beyond what is encoded in the register, event and telemetry streams.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it only a subset? Might be good to include in the spec.

Copy link

@avatarneil avatarneil May 7, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's what the second sentence is saying, but maybe there needs to be more language to elaborate upon it. Provider doesn't have a notion of non-event telemetry (closest thing is route in the Provider /trips endpoint), and it also doesn't have an always-present vehicle registry that can be polled (the Provider /vehicles endpoint only returns vehicles in the PROW), so there are some additional pieces of info that need to be in the Provider /trips endpoint that are unnecessary to send to Agency because Agency already has them.


The requirements for how soon a trip record must be posted after is part of the Service Level Agreement between Agencies and Providers.

**Endpoint:** `/trips`
**Method:** `POST`
**[Beta feature][beta]:** No
**`data` Payload:** `{ "trips": [] }`, an array of objects with the following structure

| Field | Type | Required/Optional | Comments |
| ----- | -------- | ----------------- | ----- |
| `provider_id` | UUID | Required | A UUID for the Provider, unique within MDS. See MDS [provider list](/providers.csv). |
| `device_id` | UUID | Required | A unique device ID in UUID format |
| `trip_id` | UUID | Required | A unique ID for each trip |
| `trip_duration` | Integer | Required | Time, in Seconds |
| `trip_distance` | Integer | Required | Trip Distance, in Meters |
| `start_time` | [timestamp][ts] | Required | |
| `end_time` | [timestamp][ts] | Required | |
| `parking_verification_url` | String | Optional | A URL to a photo (or other evidence) of proper vehicle parking |
| `standard_cost` | Integer | Optional | The cost, in the currency defined in `currency`, that it would cost to perform that trip in the standard operation of the System (see [Costs & Currencies][costs-and-currencies]) |
| `actual_cost` | Integer | Optional | The actual cost, in the currency defined in `currency`, paid by the customer of the *mobility as a service* provider (see [Costs & Currencies][costs-and-currencies]) |
| `currency` | String | Optional, USD cents is implied if null.| An [ISO 4217 Alphabetic Currency Code][iso4217] representing the currency of the payee (see [Costs & Currencies][costs-and-currencies]) |

201 Success Response:

_No content returned on success._

400 Failure Response:

| `error` | `error_description` | `error_details`[] |
| -------------------- | ------------------------------------------------- | ------------------------------- |
| `bad_param` | A validation error occurred. | Array of parameters with errors |
| `missing_param` | A required parameter is missing. | Array of missing parameters |

**Endpoint:** `/trips`
**Method:** `GET`
**[Beta feature][beta]:** No
**`data` Payload:** `{ "trips": [] }`, an array of objects with the same structure as the POST flavor

The `/trips` GET API should allow querying trips with the following query parameters:

| Parameter | Format | Expected Output |
| --------------- | ------ | --------------- |
| `start_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 a start 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. |
| `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. |

[Top][toc]

## Stops

The `/stops` endpoint allows an agency to register city-managed Stops, or a provider to register self-managed Stops.
Expand Down Expand Up @@ -329,6 +380,7 @@ If `stop_id` is specified, `GET` will return an array with a single stop record,
[Top][toc]

[beta]: /general-information.md#beta-features
[costs-and-currencies]: /general-information.md#costs-and-currencies
[general]: /general-information.md
[geography-driven-events]: /general-information.md#geography-driven-events
[error-messages]: /general-information.md#error-messages
Expand Down