Agency PUT Stops payload
thekaveman opened this issue · 7 comments
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_disablednum_places_disabled can be updated? Some other fields that seem like they could/should be updated via this endpoint:
num_vehicles_availablenum_vehicles_disabledrental_methodsnum_places_availabledevicesimage_url
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?
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).
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.
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
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.
OK check out the difference in OpenAPI and LMK if this looks good: