Project API: Add "project" to the URL path

[tompollard]

The API that was added in In #1697 has two endpoints: /api/v1/published and /api/v1/published/SLUG/VERSION.

In future we may want to serve non-project information (e.g. platform details; user details; license details; news items; etc), so should project appear in these path?

e.g. should the URLs be /api/v1/project/published and /api/v1/project/published/SLUG/VERSION?

[kshalot]

The proposal from our call regarding what's returned on different parts of the path:

• /api/v1/project/published - all published projects
• /api/v1/project/published/<slug> - all versions of the project with slug=<slug>
• /api/v1/project/published/<slug>/<version> - <version> of the project with slug=<slug>
• /api/v1/project/published/<slug>/latest - latest version of the project with slug=<slug>

This should be the most clear for developers using the API + it allows access to all the relevant data in a consistent way.

[tompollard]

Sounds good to me, thanks @kshalot. @Rutvikrj26 please could you reorganise the API following this pattern?

[bemoody]

/api/v1/project/published//latest - latest version of the project with slug=

I think this leads to bad habits.

If you're doing something automated, you generally don't want to know "what is the latest version", you want to know "what is the latest version with a specific major version number" or even a specific major and minor version.

(For example, I think the current behavior of wfdb-python is poorly designed in this regard.)

I would suggest that, for example, /api/v1/project/published/mitdb/1.* points to the latest version starting with 1., and /api/v1/project/published/mitdb/1.0.* points to the latest version starting with 1.0..

Not supporting "latest" encourages better practices from application developers which in turn gives data authors the freedom to make large-scale improvements.

[tompollard]

See: MIT-LCP/wfdb-python#439 for some related discussion about /latest. I see Benjamin's point that for ensuring reproducible downstream code, we might want to be careful about allowing API calls to latest. Side note, I still think https://physionet.org/content/SLUG/latest is a useful URL pattern to support for project URLs.

[tompollard]

@bemoody When I think about this a little more, since /api/v1/project/published/<slug>/latest is retrieving metadata, rather than the data itself, I think the versioning issue is less relevant.

For retrieving data, I agree that we should be trying to ensure people fix the (major) version. If people are just trying to get information about the latest version, it seems less of a problem to do this via /latest

[bemoody]

I'm not sure what distinction you're trying to draw, what is "metadata" and what is "data"?

Do you have a concrete example of an application that really needs to be able to query "what are the details of the latest published version of mitdb?" in a single request, and wouldn't be satisfied by "what versions of mitdb are published?" followed by "what are the details of version 1.0.0 of mitdb?"