Provide a project's user roles via the JSON API.

[warsaw]

What's the problem this feature will solve?
Retrieving a project's users is not possible via the JSON API. This isn't secret information though, because that information can be scraped from the project's HTML page. That's pretty inconvenient though, requiring tools like BeautifulSoup and tricky parsing of deep HTML documents. It would be so much better if the information were simply available in the "info" dict of the project's JSON API.

Describe the solution you'd like
Add a "users" key to the "info" dictionary of the project's JSON API. Why "users"? The HTML page calls them "maintainers", however the JSON dict already has fields for "author", "author_email", "maintainer", and "maintainer_email". Plus, if you look at the view for the project HTML page, they access the project's .users field. So this seems like the most minimal addition that still makes sense.

Additional context
This is related to #15769

I have a branch I'll be pushing soon.

[miketheman]

This information is also currently available via the XML-RPC API (as much as I don't want to encourage it's use, it's there, folks use it for whatever reason, and is cached for ~48 hours (I'm a little fuzzy on how, if ever, it gets invalidated based on change.)

Almost all the data returned in the current JSON API response is static, and user-driven changes are only from uploading a new release.

It's unclear to me whether changes to a project's Owner/Maintainer roles does or should invalidate caches, or whether the responses to this API are fine with being stale for a period of time.

Re: key naming and structure for accuracy sake, maybe consider a "roles": {"owners": [<username>, ...], "maintainers": [...]} structure, since that's what they are.

[warsaw]

Hi @miketheman

Thanks for the reminder about the XML-RPC API. I'm with you, I don't want to encourage its use either! 😄

Almost all the data returned in the current JSON API response is static, and user-driven changes are only from uploading a new release.

I'm not sure what this means. There is information in the project JSON endpoint that actually comes from the latest upload, which is weird on the face of it, but understandable given how PyPI works and the API, so let's ignore that for now. But it does mean that whenever a project gets a new upload, some bits of that response change (IIUC of course).

It's unclear to me whether changes to a project's Owner/Maintainer roles does or should invalidate caches, or whether the responses to this API are fine with being stale for a period of time.

Are you talking about caches inside warehouse itself?

Re: key naming and structure for accuracy sake, maybe consider a "roles": {"owners": [, ...], "maintainers": [...]} structure, since that's what they are.

That is a fantastic idea, thanks! Let me work on an update.

[miketheman]

Almost all the data returned in the current JSON API response is static, and user-driven changes are only from uploading a new release.

I'm not sure what this means. There is information in the project JSON endpoint that actually comes from the latest upload, which is weird on the face of it, but understandable given how PyPI works and the API, so let's ignore that for now. But it does mean that whenever a project gets a new upload, some bits of that response change (IIUC of course).

Heh, I should not have said static, since it's not 🤦 My intent was to convey that the details that are emitted on that endpoint comes from release metadata uploaded, vs anything that can be changed on PyPI itself by the owner user.
If no new release is uploaded, then should this endpoint change? With this approach, the response would change, since the user-to-role mapping has changed.

It's unclear to me whether changes to a project's Owner/Maintainer roles does or should invalidate caches, or whether the responses to this API are fine with being stale for a period of time.

Are you talking about caches inside warehouse itself?

I'm referring to the CDN cache in front of warehouse API calls

[warsaw]

My intent was to convey that the details that are emitted on that endpoint comes from release metadata uploaded, vs anything that can be changed on PyPI itself by the owner user.

Ah, I see what you're saying. Other than the project name (which can't be changed), and maybe docs_url and last_serial, all the other bits of data come from the latest release. It's strange, and in a proper REST API, I wouldn't include any latest release information.

If no new release is uploaded, then should this endpoint change? With this approach, the response would change, since the user-to-role mapping has changed.

I don't think the endpoint itself should change. It'll still be a GET /pypi/sampleproject/json request, but as you say, the response would change. And given...

I'm referring to the CDN cache in front of warehouse API calls

... is that an argument against exposing this data on the existing JSON endpoint? Does warehouse itself do anything to the CDN? I think it should be okay; it's not like the project's HTML page doesn't also change, invalidating the CDN cache, and I bet that's hit way more often than the JSON API.

[miketheman]

Hey @warsaw ! Another use case surfaced with regards to org membership - here's two examples:

• https://pypi.org/project/linehaul/ is owned by an org only
• https://pypi.org/project/trove-classifiers/ has both org and owner

These should provide some ideas on how to reshape the response for this data.

@ewdurbin also brought up that the changes here should probably not be returned on any release calls, only on the project, since the release details are a "snapshot" of what happened in that release. See all_releases param for an example of how we change the data shape on response

[warsaw]

@ewdurbin also brought up that the changes here should probably not be returned on any release calls, only on the project, since the release details are a "snapshot" of what happened in that release. See all_releases param for an example of how we change the data shape on response

Excellent point. I'll push that change.

[warsaw]

Another use case surfaced with regards to org membership - here's two examples

So in my current branch, I add ["info"]["roles"] mapping to a dictionary of (user) roles, e.g. owner and maintainer. Is the idea that we'd want to include team_project_roles and organization.roles too? It seems like that could get complicated, perhaps too much so for this branch. In the trove-classifier my current PR would include the owner but not the org.

Aside: I don't (yet) understand the difference between org roles and team roles.

It makes sense to add org and team info to the JSON API, eventually. But without a proper REST API, I wonder if now's not the time for that?