Endpoint Effort: Host with querying or consumer with processing?

[schnuerle]

How dynamic should the endpoints be? Should the processing be done on the host’s side with dynamic parameters and filtering being possible, or should the endpoints be more static and serve larger amounts of data at once with less querying? The former is more complex and likely requires third parties, where the latter may be easier for cities to implement on their own.

Data spec vs API spec. Do the dynamic, realtime, availability aspects get pulled out into their own endpoints as a kind of add on, instead of being optional inside of other endpoints. Should there be a simple way to implement and more complex ways to implement, as a way for cities to choose. Could use a distribution option (flat file vs API) like in MDS Policy.

[schnuerle]

Some advanced query parameters from the document that have been suggested for curb Zone endpiont, that would need to be supported by the city hosting the endpoint:

• time: An RFC 3339 date/time string that specifies a particular moment in time. If not present, defaults to the current time. This is used for:
  • the timing of availability data (if supplied)
  • evaluating include_use and exclude_use below
  • determining which regulations to include (server MUST NOT include regulations for which time is before effective_time or at or after end_time).
• include_use: If specified, contains a string containing a user class (or the string "all"), the pipe character |, and either "parking", "loading", or "standing" (e.g., "truck|loading"). Returned Curb Zones MUST allow the specified activity at the specified time for the specified user class. MAY be specified multiple times, in which case returned Curb Zones may match any of the supplied uses.
• duration_minutes: If specified, a vehicle matching a user class in include_use must be able to perform the specified activity for at least this many minutes (e.g., to find Curb Zones allowing at least two-hour parking, specify include_use=all|parking and duration_minutes=120).
• exclude_use: If specified, contains a string containing a user class (or the string "all"), the pipe character |, and either "parking", "loading", or "standing" (e.g., "truck|loading"). Returned Curb Zones MUST NOT allow the specified activity at the specified time for the specified user class (though they MAY allow the activity for a subset of users in the class; e.g., if "commercial|loading" is specified, Curb Zones allowing only truck loading will be returned). MAY be specified multiple times, in which case returned Curb Zones must not match any of the supplied uses.

[schnuerle]

Comments on this from the document:

Jacob Baskin

These fields let callers delegate the work of resolving regulations to the API server, which I think is good long-term, but I worry these might be too confusing for now.

Michael Schnuerle

These are certainly useful. Did they come from work you have done? I don't think they are confusing, but I do think they make implementation harder on host. The filtering/resolution could be left to the consumer, and maybe that's best for 1.0.

Jacob Baskin

Yeah this is based on work we have done in the past. Why don't we ask cities -- TBH my feeling is anyone who can produce compliant data and build the API to begin with can probably implement this but I could be off base

Jacob Baskin

my goal in putting these in is catering to application developers who want to find loading zones that mach their use case...this is similar to how we build our driver app

Jascha Franklin-Hodge

Hmm... I'm inclined to leave these out for now to lower the implementation complexity for a city that might want to produce this API. That said, it does seem super useful for one of the common consumer use cases. Maybe we leave this as an open question for the larger group?

[SDOTPERMITS]

Accepting flat files lowers the barrier to entry very much. It can be extremely difficult for even a large city to build or have built a custom service. There can be all kinds of budgetary and bureaucratic hurdles.
This shouldn't prevent cities with the capability and desire to build queryable APIs. Cities that do support queries ought to accept at least some common parameters and respond to them in the same way. I think it still makes sense for these common operations to go into a common reference document so that consumers can rely on at least some parameters to be expected and to produce expected results

[schnuerle]

For the first release we will leave out these more advanced query parameters, and instead require more basic querying, and see if the community needs more dynamic features in the next release.

[bhamlinSDOT]

Are the query params we have defined in the main branch considered basic? I just want to confirm we've resolved the basic vs advanced question.

[schnuerle]

Yes the 4 we have are considered basic, and we are leaving off the more complex "Curb Productivity Index" for now

[jacobmalleau]

I think starting with a more static API that provides more data than can then be queried makes the most sense initially.

We can then see what specific uses cases/ data benefits users and create customized/specific APIs accordingly.

[schnuerle]

Across the spec, we are allowing flexibility in implementation, so many endpoints could be static or dynamic, or optional, leaving it up to the producer.