Agency PUT Stops payload

[thekaveman]

The PUT endpoint for Stops in Agency says this about its payload:

An array of of Stop information, where the permitted changeable fields are defined as:

Field	Required/Optional	Description
stop_id	Required	See Stops
status	Optional	See Stops
num_spots_disabled	Optional	See Stops

Is this saying that the only fields allowed in the payload are these 3?

Or is it that the full Stop object should be sent in the payload, but only these 3 (really, 2 -- presumably not the stop_id) may change?

Is it correct that only status and ~num_spots_disabled~ num_places_disabled can be updated? Some other fields that seem like they could/should be updated via this endpoint:

• num_vehicles_available
• num_vehicles_disabled
• rental_methods
• num_places_available
• devices
• image_url

[schnuerle]

I agree it seems like a lot of these fields should be allowed to be updated via Put for stops.

It looks like a lot of this Stops work was done by you @thekaveman along with @marie-x and @avatarneil about 3-4 years ago, around the time I was starting. I don't recall the intention around this for Stops, do any of you have context and thoughts?

[marie-x]

Yeah I'm not super happy with having a single object for Stop that is mutated frequently (y'all know me, I'm stuck on immutable data whenever possible to make Policy measurements maximally reproducible) - in my perfect world, there'd be a separation between immutable Stops (e.g. the address and lat/lon) and mutable Stop Status. But we're not applying Policy to Stops (yet), so I think PUT should be allowed to update any Stop field where it makes sense to do so (e.g. num_places_available but NOT stop_id).

[avatarneil]

Agreed, I think that we should broaden the umbrella of things that can be updated. IIRC, in the initial drafts I don't think that I even included PUT methods, because I figured that the Stop management could be handled outside of the spec, and the spec would only handle reading of Stops. I think that by expanding the properties that can be updated via a PUT, we can better support provider-managed Stops.

[schnuerle]

So to wrap up, these items should now be allowed to be changed via PUT within Stops:

• last_updated
• num_vehicles_available
• num_vehicles_disabled
• rental_methods
• num_places_available
• num_places_disabled
• devices

[marie-x]

The original intent was for the regulating body to collect and publish that data through whatever mechanisms, and publish it read-only via the Stops endpoint, but if it's a Provider-maintained and -monitored Stop, then yeah, those fields should be mutable. More likely scenario is Provider-maintained Stops will use the Provider API.

[thekaveman]

OK check out the difference in OpenAPI and LMK if this looks good:

• POST: https://openmobilityfnd.stoplight.io/docs/mds-openapi/b3ea061e37756-stops#request-body
• PUT: https://openmobilityfnd.stoplight.io/docs/mds-openapi/362ec313b670d-stops#request-body
• GET: https://openmobilityfnd.stoplight.io/docs/mds-openapi/bd99c2440acf4-stops#response-body

[schnuerle]

Looks correct! Updated with commits here and here.