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/

[adriens]

🙏

[adriens]

👏

[MartinPetkov]

Would it be possible to update this branch to pick up some of the latest versions?

PS I also wholeheartedly support having this PR reviewed and merged @captn3m0 🙂

[marcwrobel]

Would it be possible to update this branch to pick up some of the latest versions?

Done. Note that some fields have been renamed following #4931, see 1d44f32. Let me know if you notice something wrong.

[TimBrown1611]

hi! was this API v1 deployed?

[marcwrobel]

hi! was this API v1 deployed?

Yes, the preview is deployed on https://deploy-preview-2080--endoflife-date.netlify.app/docs/api/v1/.

[TimBrown1611]

hi! was this API v1 deployed?

Yes, the preview is deployed on https://deploy-preview-2080--endoflife-date.netlify.app/docs/api/v1/.

Hi! Thanks,
When it will be officially deployed? it seems like a demo

[flo7000]

Hello all
any updates on the deploy date? I'm waiting for it because it's the dependency for my task (mentioned in #2108 (comment) )

[marcwrobel]

None on my side. I am still waiting for some reviews (at least one from @captn3m0). I would like the payloads format and field names to be confirmed before merging this, because once it's released we won't be able to change it easily.

[TimBrown1611]

@captn3m0 do you think it will be merged soon? this API call adds some information which can be very useful for other tools :)

[MartinPetkov]

@marcwrobel Could you please rebase this branch and update the preview API when you have time?

[glauberferreiranees]

Is there a planned date to release the new version of API? A preview of Swagger is available?

[marcwrobel]

Could you please rebase this branch and update the preview API when you have time?

Done.

Is there a planned date to release the new version of API?

Nope, still waiting for some reviews.

A preview of Swagger is available?

Yes, through the preview URL : https://deploy-preview-2080--endoflife-date.netlify.app/docs/api/v1/.