Endoflife api/v1

[marcwrobel]

This is a major rework of the API that fixes a lots of issues, but introduces a lot of breaking changes. See https://github.com/endoflife-date/endoflife.date/blob/2062-expose-product-info-api/CHANGELOG_API.md for more information.

Note that I thought of disabling API generation in development (using JEKYLL_ENV like the Jekyll Feed plugin - see https://github.com/jekyll/jekyll-feed/blob/master/lib/jekyll-feed/generator.rb#L145), but I finally reverted it. It does not work well with Netlify preview, and generate production URL (i.e. https://endoflife.date/ URLs) in development which makes testing more difficult.

[captn3m0]

Few notes:

• Want to use https://jekyllrb.com/docs/plugins/generators/ to better read our metadata
• I want to update all our Product pages' metadata as they're read using a Jekyll hook to augment the data (set defaults, validate etc), and use this common data in all places (API, HTML etc). That way, the heavy lifting of standardization is only done once. Will file a PR for this soon.
• Need to add redirects as well. We generate the netlify _redirects file, so hopefully a single redirect entry should work for this, but might need some tweaking.

[captn3m0]

Wrote up a quick draft for the specification: endoflife-date/releases.json#1

[marcwrobel]

I modified the plugin to use a generator. The script itself is much more simple, but the corresponding template will be a bit complex (like the product.html template). But it cannot be avoided if we want to achieve API / HTML parity without that.

[marcwrobel]

• Need to add redirects as well. We generate the netlify _redirects file, so hopefully a single redirect entry should work for this, but might need some tweaking.

Which redirects ? The redirects based on alternate_urls or the /api -> /api/v1 redirect ?

[captn3m0]

The v1 redirects.

[marcwrobel]

The v1 redirects.

Ok, that can wait if we decide to give time to migrate to client's maintainers.

[marcwrobel]

@captn3m0, what is your opinion about those subjects :

1. API structure: should we move the /api/v1/<product>.json files the /api/v1/<product> directory. I think it makes more sense to have all the product resources at the same place. But we will have to rename the json file (for example to /api/v1/<product>/info.json).
2. Response content: should all attributes be always present. For example if a product cycle does not have latest attribute (and releaseColumn: false), should we have "latest": null for the cycle or should we remove the latest attribute ? I don't know what is best, but I think always having those attribute is more explicit.

[marcwrobel]

@captn3m0 I have worked on the API v1, here is where I am :

• https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/all.json
• https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/android/info.json
• https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/debian/info.json
• https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/macos/info.json

There are still a lot of things to do but it's going well so far.

[captn3m0]

permalink -> html_url perhaps? (And should we change link -> url as well?)

Don't like using /info.json in the URL. We can maybe do /api/v1/products/:name.json instead, if we want to add an additional namespace (products in this case).

[marcwrobel]

Don't like using /info.json in the URL. We can maybe do /api/v1/products/:name.json instead, if we want to add an additional namespace (products in this case).

By introducing the :name/info.json I tried to introduce a namespace in the API for the product, so I am not fan of /api/v1/products/<product>.json. Better to have /api/v1/<product>.json in this case. To bad we cannot respond to /<product>/ !

[marcwrobel]

@captn3m0, another test, with a a new schema : https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/android/info.json. Just toying a little bit, this is in no way a proposal. But let me know what you think of the ideas.

• I grouped all the links together (and we can add more links later if we want).
• I grouped all the latest version informations (so that later if its needed the schema could be reused - for instance for the list of all versions)
• I rename "releases" to "cycles". The release term is sometime confusing: is a a version, a major.minor release, a release cycle... ?
• I used name and label for both products and cycles (for consistency).
• I rename the releaseDate to date (not sure I like this one - and I am sure you will not like it ;)).

I am also wondering about the eol / discontinued fields. They seem close and I wondered if having only the eol field. Will have to read again the spec you wrote ;).

[captn3m0]

To bad we cannot respond to // !

Think we can, we have Netlify header support. It's hacky, but if we set permalinks for these files correctly, and set content-type headers (application/json) from Netlify _headers file, it should work.

[marcwrobel]

Think we can, we have Netlify header support. It's hacky, but if we set permalinks for these files correctly, and set content-type headers (application/json) from Netlify _headers file, it should work.

Just tried in with /api/v1/all.json, works well : https://deploy-preview-2080--endoflife-date.netlify.app/api/v1/.

# Rewrite for /api/v1/
/api/v1/       /api/v1/index.json       200!

I tried to also redirect /api/v1/index.json to /api/v1/ but it did not work:

# Rewrite for /api/v1/
/api/v1/       /api/v1/index.json       200!
/api/v1/index.json       /api/v1/

[marcwrobel]

Added a GitHub workflow so that the OpenAPI spec is validated using vacuum and checked all the generated JSON using wiretap (thanks @jamietanna for the tips !): everything looks good.

I don't plan any more change, so I will merge this PR Saturday or Sunday unless there are any objections or further feedback.

CC @endoflife-date/everyone

[jamietanna]

Awesome stuff! I'll take another look next couple of days, and will start migrating my integrations over to the new API 👏🏽

Great work on this, it's been literally a long time coming 😁

[adriens]

A major milestone 🤩

[marcwrobel]

Let's merge ! 🤞

[marcwrobel]

The new API is now live. Thanks to everyone involved, especially @jamietanna !

$ http --body https://endoflife.date/api/v1/
{
    "generated_at": "2025-05-03T14:24:53+00:00",
    "result": [
        {
            "name": "products",
            "uri": "https://endoflife.date/api/v1/products"
        },
        {
            "name": "categories",
            "uri": "https://endoflife.date/api/v1/categories"
        },
        {
            "name": "tags",
            "uri": "https://endoflife.date/api/v1/tags"
        }
    ],
    "schema_version": "1.0.0",
    "total": 3
}

[marcwrobel]

For existing users of the old API: nothing should changes, the old API is still generated to give you time to migrate to API v1. It will be decommissioned in one year or more (no final decision made yet).

[adriens]

OMG @marcwrobel : today is the day ❔ 😍