Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Endoflife api/v1 #2080

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Endoflife api/v1 #2080

wants to merge 3 commits into from

Conversation

marcwrobel
Copy link
Member

@marcwrobel marcwrobel commented Dec 17, 2022 •
edited
Loading

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.

@marcwrobel marcwrobel linked an issue Dec 17, 2022 that may be closed by this pull request
Expose product level information in the API #2062
Open
@captn3m0
Copy link
Member

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
Copy link
Member

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

@marcwrobel marcwrobel force-pushed the 2062-expose-product-info-api branch 3 times, most recently from 5e0f74c to f8e238b Compare December 17, 2022 16:13
@marcwrobel
Copy link
Member Author

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
Copy link
Member Author

  • 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
Copy link
Member

The v1 redirects.

@marcwrobel
Copy link
Member Author

marcwrobel commented Dec 17, 2022 •
edited
Loading

The v1 redirects.

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

@marcwrobel
Copy link
Member Author

marcwrobel commented Dec 18, 2022 •
edited
Loading

@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.

This was referenced Dec 19, 2022
Open
Open
@captn3m0 captn3m0 mentioned this pull request Dec 20, 2022
Open
@marcwrobel marcwrobel force-pushed the 2062-expose-product-info-api branch 2 times, most recently from a301630 to aa324fd Compare December 20, 2022 14:12
@marcwrobel
Copy link
Member Author

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

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

@captn3m0
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member Author

@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
Copy link
Member

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 marcwrobel force-pushed the 2062-expose-product-info-api branch 6 times, most recently from 1e35540 to d6438df Compare December 22, 2022 13:59
@marcwrobel
Copy link
Member Author

marcwrobel commented Dec 22, 2022 •
edited
Loading

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 commit that referenced this pull request Nov 5, 2023
@marcwrobel
Add support for custom columns
08e8472 
They can be used for documenting things such as related runtime versions, custom dates that cannot
be expressed using the default columns, etc. See the documentation in the contribution guide for
more information on how to use them.

This is only an initial support and:

- The allowed positions have been limited to positions that have a chance to be used. More positions
  may be added in the future if needed.
- Those properties may also be exposed in the new API responses (after #2080).

Closes #3642.
marcwrobel added a commit that referenced this pull request Nov 5, 2023
@marcwrobel
Add support for custom columns (#4002)
7489fc2 
They can be used for documenting things such as related runtime versions, custom dates that cannot
be expressed using the default columns, etc. See the documentation in the contribution guide for
more information on how to use them.

This is only an initial support and:

- The allowed positions have been limited to positions that have a chance to be used. More positions
  may be added in the future if needed.
- Those properties may also be exposed in the new API responses (after #2080).

Closes #3642.
@marcwrobel
Copy link
Member Author

@captn3m0, any chance to see this reviewed (and hopefully merged !) before the end of the year ? I spent a lot of time on this and I am a little sad that I had little feedback (thanks to those that did it 👍).

@adriens
Copy link
Contributor

adriens commented Dec 17, 2023

OMG that would an awesome 🎅 🎁

BiNZGi
BiNZGi approved these changes Dec 18, 2023
View reviewed changes
Copy link
Member

@BiNZGi BiNZGi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried several endpoints/combinations at https://deploy-preview-2080--endoflife-date.netlify.app/docs/api/v1/ and all LGTM. I vote for merging this in current shape 👍

@adriens
Copy link
Contributor

adriens commented Dec 18, 2023

Same here, my daily tests are pretty stable
image

@marcwrobel marcwrobel force-pushed the 2062-expose-product-info-api branch 2 times, most recently from 5bb1e3b to 9a06292 Compare December 30, 2023 13:41
@adriens
Copy link
Contributor

adriens commented Feb 17, 2024

🙌

@marcwrobel marcwrobel force-pushed the 2062-expose-product-info-api branch from c22d30b to 67af7fd Compare March 9, 2024 08:34
@adriens
Copy link
Contributor

adriens commented Mar 18, 2024

🙏

@adriens
Copy link
Contributor

adriens commented Mar 31, 2024

👏

@MartinPetkov
Copy link
Contributor

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 marcwrobel force-pushed the 2062-expose-product-info-api branch from 4d2ea74 to 1d44f32 Compare June 23, 2024 12:09
@marcwrobel
Copy link
Member Author

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.

This was referenced Jul 1, 2024
Open
Open
@marcwrobel
First version
89426a1
@marcwrobel
Add API v1 (#2595, #2425, #2331, #2066, #2062, #1762, #759, #394, #2530)
4c55927 
This is a major rework of the API with a lot of breaking changes. See CHANGELOG_API.md for more information.

Note that we 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 it was finally reverted. It does not work well with Netlify preview, and generate production URL (i.e. https://endoflife.date URLs) in development which makes it difficult to use.
@marcwrobel
Renames following #4931
9b9a9c5
@marcwrobel marcwrobel force-pushed the 2062-expose-product-info-api branch from 1d44f32 to 9b9a9c5 Compare July 6, 2024 07:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@usta usta usta approved these changes

@adriens adriens adriens approved these changes

@BiNZGi BiNZGi BiNZGi approved these changes

@captn3m0 captn3m0 Awaiting requested review from captn3m0

@hugovk hugovk Awaiting requested review from hugovk

Assignees
No one assigned
Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Expose product level information in the API
9 participants
@marcwrobel @captn3m0 @adriens @usta @BiNZGi @hugovk @viceice @generalmimon @MartinPetkov