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.

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

Add a JSON "pseudo-API" #61

merged 9 commits into from Jul 6, 2019


None yet
2 participants
Copy link

commented Jun 23, 2019

This commit fixes #22, although not precisely as stated.

Instead of /json/[tool] to return all the data about a specified tool as JSON, I've opted for /api/[tool]/[releaseCycle].json

The reasons are:

  • /api/[something].json seems like a more 'standard' format for an API URL
  • Using /api instead of /json means other data formats can be returned in future using the same pattern
  • /api/[tool]/[releaseCycle].json enables users to automate a check for the end of life date of whichever version of a tool they are using

The last point is key IMO, because it enables to be integrated into build pipelines.


Data Format

The format in which people have supplied 'releaseCycle' is not always consistent, e.g.:

  • releaseCycle: "v3.9" (alpine)
  • releaseCycle: "CentOS 6" (centos)
  • releaseCycle: 'Debian 6 "Squeeze" (LTS)' (debian)
  • releaseCycle: 6 (java)

For use in a build pipeline, it would be better to enforce consistency, limiting the values to [major].[minor] (i.e =~ /^\d+\.\d+$/)

Right now, users of the API would need to know the format of the data for their specific tool before they could check it, which makes the API less useful.

Build process

By adding a 'compilation' stage, using make, it is no longer possible to create a new tool entry solely using the github web interface.

This could be fixed by adding a build pipeline like this, i.e. where the build process aborts if the change which triggered the build is a commit to the 'api' directory (otherwise the build process would go into an endless loop, since every build would result in a commit, which triggers a build).

digitalronin added some commits Jun 23, 2019

Add a makefile to build api directory
The api directory will contain a directory for each tool.
The api/tool directory will contain a JSON file for each
releaseCycle listed in the tools/ file.
Add script to output JSON release data for a tool
This script takes a markdown filename (e.g. 
tools/ as input and outputs an 
api/[tool]/[version].json file for each 
releaseCycle in the markdown source, where [tool] 
is the permalink value and [version] is the
releaseCycle value.

The contents of the JSON file is the data in the
release, minus the releaseCycle.
Update wrt. new build process
* Contributors must run `make` after creating
their YAML file
* Because they need to run `make`, it is no longer
viable to create the new YAML file directly in

@jhnferraris jhnferraris requested a review from captn3m0 Jun 24, 2019


This comment has been minimized.

Copy link

commented Jun 24, 2019

Can you look at running this from a Jekyll hook instead?

The :after_init hook is the first to run, before files are read from disk, and we can use this to generate the files. There is documentation at

I was planning to use the symlink approach from jekyll/jekyll#3041 (comment), but since your design calls for an unknown number of templates, this might be hard to setup with symlinks.

I still think it makes sense to provide a unified API per tool as well (alongside the per-release cycle), which is a JSON version of the complete page contents for any given tool. We can keep that for later though?

digitalronin added some commits Jun 24, 2019

Remove the api/*.json files
We will build those every time the site is 
deployed, via a plugin script.
Remove the makefile-based build process & script
Also, revert the contribution instructions to
previous state.
Git ignore api/ directory
api/*.json files are built every time jekyll runs,
so there's no point including them in the repo.

This comment has been minimized.

Copy link
Contributor Author

commented Jun 24, 2019

It seems all that's necessary is a ruby script in _plugins/, rather than using a hook (which is just as well, because I couldn't find any useful information on how to use hooks).

This builds all the api/*.json files whenever jekyll runs.


This comment has been minimized.

Copy link

commented Jun 25, 2019

Thanks a lot 👍

Will review this 🔜

@captn3m0 captn3m0 merged commit 3e3d090 into captn3m0:master Jul 6, 2019

2 of 5 checks passed

Header rules No header rules processed
Pages changed 41 new files uploaded
Redirect rules No redirect rules processed
Mixed content No mixed content detected
deploy/netlify Deploy preview ready!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.