Make Policy/Geography API Endpoints Optionally Public

[quicklywilliam]

Explain pull request

The value of having Policy API endpoints be public has come up in several different contexts. In particular, in the development of #503, it has been pointed out that a hypothetical "bad actor" at a city could create arbitrarily small or specific Policy regions that undermine the stated goal of protecting rider privacy. For example, this bad actor could create policy regions around a political protest and the home of a specific individual and receive events that reveal the trips of this individual to/from a protest. In this hypothetical example, the value of a public Policy API endpoint is clear: anyone could see what is happening and ask the bad actor to account for creating such targeted policy regions.

In less specific and hypothetical cases, there is public benefit from making Policy data "open data". For example, residents could monitor the vehicle caps over time and enterprising developers could add speed limits and no parking zones to their apps.

This change may raise concerns that vehicle caps and other such data are proprietary data. There may be competitive concerns here, but I don't think they should overrule the public benefit of publishing this data. There are no individual privacy concerns or trade secrets in this data, and it is unlikely that cities could shield this data from a records request.

Is this a breaking change

No.

Impacted Spec

Policy.

[schnuerle]

I like the clear language you suggest: "Policy API endpoints shall be public."

But I wonder if instead it should be left up to the agency? Eg "We recommend that the Policy API endpoints be made public and non authenticated, but leave it to the discretion of the agency." Especially for the 1.1.0 release to make the change non-breaking.

Note I have teed up this suggestion in the Geography API with this language:

"Optionally, an Agency may decide to make these endpoints unauthenticated and public, which could be done in conjunction with the /policy endpoints."

We should add some language in the spec about the reasons and benefits of making it public.

[schnuerle]

Renamed so it can apply to both Policy and Geography endpoints, with similar language in both, since they rely on each other and are both published by cities and both don't contain sensitive data.

If anyone has concerns about either of these APIs containing information that should not be made public, or should not be released through an open records request, please leave your thoughts here.

Here is suggestion for wording, which should go in a new section in General Information:

Optional Authentication

An agency may optionally decide to make both the Policy and Geography endpoints unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, allows third parties to ingest this valuable information into their applications and services, and reduces the technical burden on providers to use these endpoints.

Note if implementing the beta feature Geography Driven Events, both Policy and Geography must be public.

Each API's page will have some language that links to this information.

An agency may optionally decide to make this endpoint unauthenticated and public. See the Optional Authentication section for details.

[drewda]

Glad that public access is under consideration for the MDS endpoints that concern public, rather than rider specific, info. We've long been waiting to see if it could be relevant to add MDS to the Transitland open data aggregation platform. If some cities or operators start serving public MDS data, we'll consider adding to the Transitland Atlas directory and to Transitland v2 website and APIs.

[marie-x]

@schnuerle I like your Optional Authentication language.

[schnuerle]

@quicklywilliam do you think you can make these changes here, along with resolving conflicts with dev? Or you can edit this PR to "Allow edits from maintainers" and I can do that. If those options don't work for you we could close this PR and open a new one.

I've revised the proposed wording below based on some feedback and discussions.

New section in General Information with appropriate links added:

Optional Authentication

Authorization of the Policy and Geography APIs is no longer required and will be deprecated in next major release with these endpoints becoming optionally private instead of optionally public. An agency may optionally decide to make both the Policy and Geography endpoints unauthenticated and public. This allows transparency for the public to see how the city is regulating, holds the city accountable for their policy decisions, and reduces the technical burden on providers to use these endpoints. A side benefit is that this allows third parties to ingest this information into their applications and services for public benefit.

Note if implementing the beta feature Geography Driven Events, both Policy and Geography must be public.

Each Policy/Geography API main page will have this language that links to this new section.

Authorization is not required. An agency may decide to make this endpoint unauthenticated and public. See Optional Authentication for details.

[quicklywilliam]

Done!

[schnuerle]

@quicklywilliam to make some final updates to this PR based on discussions the last 3 weeks and then this will be ready for the release candidate on Dec 15.

[quicklywilliam]

Updated language with @schnuerle suggestions which reflect the WG's feedback.

[schnuerle]

Thank you for your work on this, looks good!