API<>Website Parity

[captn3m0]

We do a lot of templating and fixing up in the product layout (https://github.com/endoflife-date/endoflife.date/blob/master/_layouts/post.html) that doesn't reflect into the API easily. So creating a discussion to document these issues (and any more related API usecases), so we can track them and decide on how to tackle them best.

• permalink is used as default iconSlug

Probably for the best if we drop the default value, and enforce iconSlug instead. Being explicit is better here, I think, causes less confusion.

• Columns Visibility

The website can hide/show columns, all of which have a default value as well.

• Color

Probably not needed in the API, but we provide a green/orange/red coloring based on some rules.

• Changelog Templating

We support changelog templates, that aren't rendered. Direct links are rendered, on the other hand. (See https://endoflife.date/api/godot.json vs https://endoflife.date/api/electron.json)

• Relative Dates

The website shows relative dates, the API doesn't.

• Sorting

We sort releases by sortOrder for the website, not for the API

• Missing Keys

Since the API currently only deals with release cycles, there is no information from our top level keys (such as command, category, releaseImage, or releasePolicyLink in the API). This will likely be a breaking change. We should probably also send a markdown+html version along in the API for some more interesting use-cases.

• Alternate URLs

Not mentioned in the API. Probably not needed.

• Link headers

The website links to the API via a Link header (curl -sI https://endoflife.date/electron |grep link) but we don't link in the other direction.

• LTS Labels

We mark releases as LTS using lts: true, which shows up, but as we track #653, we should support LTS labels in the API as well.

• Release Labels

Release labels are templates, and the templates should be respected. They are also overwritten on a per-release basis, so that should also be implemented.

---

All of the above, along with a tendency for our API URLs to break is what I'd like to solve before we can move our API from Alpha->Beta or stable status.

[marcwrobel]

With #2062 the API will use a Jekyll generator and the API responses will be generated using a template. That will add some flexibility to add some of the missing keys. #2062 will also add product-level information to the <product>.json file.

Other comments :

• permalink is used as default iconSlug: I also think iconSlug should be explicit (much more manageable at API side), see Make iconSlug explicit for all products #2085,
• Color: I also think it is not needed in the API
• Changelog Templating: it can be resolved in Expose product level information in the API #2062
• Relative Dates: I do not think it is needed in the API, the API is not for humans
• Sorting: could be resolved in Expose product level information in the API #2062
• Missing Keys: some (all ?) could be resolved in Expose product level information in the API #2062
• Alternate URLs: I think it is needed, for example if we rename a product (and it is already implemented - see https://github.com/endoflife-date/endoflife.date/blob/master/_redirects)
• Link headers: yep, would be a good addition
• LTS Labels / Release Labels: could be resolved in Expose product level information in the API #2062

[marcwrobel]

Current state of #2080 regarding this discussion.

• permalink is used as default iconSlug : this has been solved with Make iconSlug explicit for all products #2085
• Columns Visibility : I don't think it matters much on API side, that's something useful only on the WebSite
• Color : I don't think it matters much on API side, that's something useful only on the WebSite
• Changelog Templating : done
• Relative Dates : I do not think it is needed in the API, the API is not for humans
• Sorting : API and WebSite display the releases by their order of declaration (sortOrder was removed)
• Missing Keys : done
• Alternate URLs: we may want to expose alternate names though ?
• Link headers: done
• LTS Labels: done
• Release Labels: done