Add /trips endpoint to Agency API

[marie-x]

Is your feature request related to a problem? Please describe.

For MDS 1.0, a significant set of changes to both Agency and Provider aligned their terminology, but left their respective APIs largely unchanged.

One capability that Provider has that Agency lacks is the ability to represent certain information about trips, including trip_duration, trip_distance, standard_cost, actual_cost, etc. Most of that information cannot be derived from Agency events, and trip_distance derived from GPS is always going to be less accurate than the odometer value.

Describe the solution you'd like

Add a /trips endpoint to Agency that is symmetrical with Provider's /trips, just push instead of pull.

The route field might be dropped or made optional, as it should be redundant with the /telemetry data.

Is this a breaking change

• No, not breaking (new functionality but no change to existing functionality)

Impacted Spec

For which spec is this feature being requested?

• agency

Describe alternatives you've considered

We (E&A for LADOT) considered adding all of those fields to the trip_end event, but that seemed to unnecessarily add many conditionally-required fields to a particular type of event, and also unreasonably force all of those fields to be calculated at the time that trip_end was submitted.

Additional context

One of the goals is to be able to have a city do data intake with Agency but re-serve that data via a Provider-style interface that tooling companies like Ride Report can connect to.

[avatarneil]

I think that for Agency, we'll likely want to omit these properties found in the Provider /trips payload:

• publication_time (not necessary because the Agency will know when it received the push)
• route (N/A because Agency has the /telemetry endpoint)
• vehicle_type (because Agency has device information already)
• propulsion_type (because Agency has device information already)
• vehicle_id (because Agency has device information already)
• provider_name (because Agency has the provider information already)

We could additionally omit the provider_id property (as Agency should be able to extract that from the authentication token), but especially as we consider the role of aggregators in MDS, keeping it explicitly encoded could be beneficial.

[schnuerle]

I think this is a good proposal and could be part of the next major release (2.0) if someone want to take it on.

[marie-x]

I can own it.

[tonial]

Hi.

I feel it would be better to keep the route property :

From a Provider point of view :
From what I see as an Agency software developer, most of the Providers already have a Provider API implemented. So they will already have the Provider Trip endpoint and the capability to aggregate the route data.
This means that if they need to implement the Agency API, there is no added work to add the route property.
If we remove route, it means the Provider will instead have to add another endpoint (Vehicle/telemetries), which implies more development, and also more time to connect to the Provider and the Agency (which sadly usually takes a lot of time)

From a Agency point of view :
Removing route would mean to add a different way to treat Provider API Trips and Agency API Trips.
It would also require to handle the Vehicle/telemetries endpoint, and to connect it with the Provider.

[schnuerle]

We will be discussing this on Thursday's MDS Working Group call. @Karcass will be going over details of a preliminary PR, which you can review here.

[avatarneil]

Hey @tonial, thanks for chiming in with some Provider POV feedback, as someone currently working from an Agency standpoint, it's always incredibly valuable to hear what things would look like on the Provider's end :)

There are a couple things from your comment I want to address (note: I may have misinterpreted some things, so please correct me if I groked it wrong).

It sounds like you're saying that because Providers who are currently operating the Provider API have already implemented route in the /trips endpoint, it'd be easy to just send that same information over to Agency, and that totally makes sense to me! But I'm not sure I follow the line of reasoning that:

If we remove route, it means the Provider will instead have to add another endpoint (Vehicle/telemetries), which implies more development, and also more time to connect to the Provider and the Agency (which sadly usually takes a lot of time)

The Agency API already has an endpoint for sending telemetry points, so if a mobility provider were to integrate with the Agency API , they'd still have to update their platform in order to send telemetry POSTs to Agency. This is true today, and I think that it'd still be true in a world where route comes along as part of a POST to an Agency /trips endpoint. One could make the argument that if there's route information included in the Agency /trips endpoint, then that alleviates the need to have the /telemetry endpoint in Agency at all; however, I believe that the Agency /telemetry endpoint covers substantially more use-cases than route within the Provider /trips endpoint does, especially when looking to the future of MDS.

The Agency /telemetry endpoint can receive telemetry updates outside of the context of a Trip, for example, if a vehicle moves when it's not currently on a passenger trip and sitting as available in the right-of-way. This is not especially common (or, at least, I imagine everyone here hopes it isn't) for micromobility, as the only time you'd really see that happen is during unauthorized activity (e.g. someone stealing the scooter off the street). This is however incredibly important when considering other modes of transportation, which MDS is going to support in the near future; for example, if you're considering a Taxi's movement, there are plenty of use cases where a regulating agency could need to receive telemetry notifications from a Taxi that is not currently on a passenger trip.

So, in essence, I think that not including the route property in the POST to the Agency /trips endpoint wouldn't impose any additional work on mobility providers, in fact, it would likely be less work (from a data-over-the-wire standpoint). I believe that the Agency /telemetry endpoint has to stick around no matter what, and Providers will have to integrate with that in order to be fully compliant with the Agency API. That all being said, depending on a particular regulating agency's requirements, it is certainly possible that they could have very light SLAs, and any information that they require to be sent to the Agency /telemetry endpoint would be easily derivable from a route that has already been computed as part of a Trip that a Provider has already built and is serving via the Provider API. There is nothing in the Agency spec that mandates that notifications to the /telemetry endpoint must be in real-time, and the differences in payload shape are largely pretty negligible I think, considering that the Agency API doesn't explicitly require much in telemetry beyond timestamp & lat/lng ('required if available' is a bit of a cop-out, heh). Of course, some regulating agencies may have more stringent requirements on-top of the Agency API spec, for example requiring accuracy with every telemetry point; but again, I think that's something that they'd likely ask to be included in the route of a Trip even if there was no /telemetry endpoint in Agency at all.

[tonial]

Hi avatarneil.

I agree with you when you say that adding route in the Agency trip API should not replace data from /telemetry as the needs that are being met by /telemetry and the route field are not the same.

But i really think that the most important thing when designing a standard that we want to be adopted by as many people as possible it to keep it as easy as possible for those same people to implement.

From my experience, using data as an agency from both provider and agency endpoints used to be really hard in MDS < 1 because of the differences.
In MDS 1.0, a huge work was made in unifying the events payload in Agency API and Provider API, and it really made things easier.

The gist of the PR it to add an endpoint in the Agency API that already exists in the provider API.
Any difference in the payload would mean that providers and agency supporting both Provider and Agency API will have to handle the Provider and Agency /trip endpoints differently (instead of exactly the same way).

[avatarneil]

@tonial Thank you for the response!

I'm pretty sure I see what you're getting at. Are you talking primarily about what would be returned from this endpoint in the Agency instance, e.g. if someone were to issue a GET to the Agency /trips endpoint? In that case, I wonder if it'd make sense to have Agency return the fully-qualified response in that case (with route, vehicle_type, all that jazz). I really struggle to see how it'd be particularly onerous for a Provider to simply remove a handful of properties when sending a POST to the /trips endpoint in Agency (with javascript, for example, it'd literally be a one-liner const { publication_time, route, vehicle_type, propulsion_type, vehicle_id, provider_name, ...tripToSendToAgency } = providerTrip), but I could certainly imagine plenty of cases where to consume from the /trips endpoint 100% schema alignment would be desirable!

That all being said, I'm still on the fence about if Agency should even have a GET /trips endpoint for reading-back trips at all (though the PR as it stands today does support this functionality), mobility providers should already know all of their own Trip information, and as long as they've gotten a 201 response back from Agency then they know the Trip successfully POSTed! A read-back GET /trips endpoint in Agency really feels like it's treading into the workflow of things that an agency/tooling company may need to do outside of the flow of information between the agency and the mobility provider, and that's historically something that the OMF hasn't wanted to include in this repo (e.g. MDS Audit, MDS Policy Author, MDS Geography Author, etc...). @schnuerle do you have any thoughts on this?

[schnuerle]

Minutes and action items from the WG meeting are here.

[tonial]

@avatarneil.
What I'm saying is that the trip payload that goes from a Provider to an Agency (either a POST to the Agency Trip endpoint, or the answer to request on the Provider Trip endpoint) should be as similar as possible.

Yes, it's easy to drop the route from the payload for the provider, but it's event easier to have the exact same payload between the two.

And from an Agency point of view it's clearly a lot more complex to aggregate data from both Agency - Telemetry and Agency - Trip endpoints to get the trip route. It would be easier to just poll data from the Provider API, and therefore, the use of a Agency Trip is limited.

I saw a lot of work made to make Agency and Provider data similar, I think it's sad to keep even small differences since it means more work to develop the API later.

[schnuerle]

This is now moved out of the 1.2.0 release and to the next release, like 2.0.0.

[marie-x]

Closing in favor of #722