Refactoring of /rest/info and /rest/releases?

[ramiromagno]

Refactoring of /rest/info and /rest/releases?

[ens-lgil]

Dear @ramiromagno,

Thank you for your suggestions.
Regarding these suggestions here are our comments:

As general remarks, the aim of the endpoint rest/info is to list diverse "generic" information regarding the PGS Catalog.
This endpoint is a good place to know the current release date and numbers, the current REST API version, the latest PGS paper, etc ...

Suggestion 1

The rest/release endpoints are only here to list the number of new data on each release.
We are hesitant to add the number of new Traits as this particular type of data can change with the ontolgies (merged traits, new traits, obsolete traits).
Furthermore, we think that the total number of entries is more suitable for the rest/info endpoint.

Suggestion 2

As I wrote it above, we view the rest/info as a place to put different type of information regarding the Catalog. Therefore we think that this is a decent place for the citation and the terms_of_use.

Suggestion 3

It makes sense to have a dedicated endpoint listing the different REST API versions and their changelogs.

Note that the changelog is already available in the https://www.pgscatalog.org/rest page (under REST API version changelog).

Although it would make sense to have it in the same way as the rest/release endpoint, we think it will be a bit overkilling to have 3 endpoints that (e.g. all/current/1.7). We believe that there won't be that many new versions in the future (at least less than the number of new releases) and therefore it should be easy to parse and filter.
The idea would be to have a unique endpoint (e.g. rest/api_versions) and a structure like this:

{
    "current": {
        "version": 1.7,
        "date": "2021-04",
        "changelog": [
            "New data 'ancestry_distribution' in the `/rest/score` endpoints, providing information about ancestry distribution on each stage of the PGS",
            "New endpoint `/rest/ancestry_categories` providing the list of ancestry symbols and names."
        ]
    },
    "previous": [
        {
            "version": 1.6,
            "date": "2021-03",
            "changelog": [
                "New endpoint `/rest/info` with data such as the REST API version, latest release date and counts, PGS citation, ...",
                "New endpoint `/rest/cohort/all` returning all the Cohorts and their associated PGS.",
                "New endpoint `/rest/sample_set/all` returning all the Sample Set data."
            ]
        },
        {
            "version": 1.5,
            "date": "2021-02",
            "changelog": [
                "Split the array of the field 'associated_pgs_ids' (from the `/rest/publication/` endpoint) in 2 arrays 'development' and 'evaluation'.",
                "New flag parameter 'include_parents' for the endpoint `/rest/trait/all` to display the traits in the catalog + their parent traits (default: 0)."
            ]
        },
        ...
    ]
}

I hope this makes sense.

Best regards,
Laurent

[ramiromagno]

Thank you Laurent for taking the time to explain. Makes perfect sense!