Example of API change documentation
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.gitignore
README.md
autocomplete.html
autocomplete.new.json
autocomplete.new.schema.json
autocomplete.old.json
autocomplete.old.schema.json
classification.html
classification.new.json
classification.new.schema.json
classification.notes.html
classification.notes.md
classification.old.json
classification.old.schema.json
config.json
details.csv.html.ftl
details.generic.html.ftl
details.header.html.ftl
details.json.html.ftl
download-genus.notes.html
download-genus.notes.md
download.html
download.new.csv
download.notes.html
download.notes.md
download.old.csv
footer.html.ftl
generate.groovy
guid-batch.html
guid-batch.new.json
guid-batch.new.schema.json
guid-batch.old.json
guid-batch.old.schema.json
index-fields.html
index-fields.new.json
index-fields.new.schema.json
index-fields.notes.html
index-fields.notes.md
index-fields.old.json
index-fields.old.schema.json
index.html
index.html.ftl
navbar.html.ftl
notes.html.ftl
package.json
search-genus.html
search-genus.new.json
search-genus.new.schema.json
search-genus.notes.html
search-genus.notes.md
search-genus.old.json
search-genus.old.schema.json
search.html
search.new.json
search.new.schema.json
search.notes.html
search.notes.md
search.old.json
search.old.schema.json
species-bulk-lookup.html
species-bulk-lookup.new.json
species-bulk-lookup.new.schema.json
species-bulk-lookup.old.json
species-bulk-lookup.old.schema.json
species-guid.html
species-guid.new.json
species-guid.new.schema.json
species-guid.old.json
species-guid.old.schema.json
species-vernacular-bulk-lookup.html
species-vernacular-bulk-lookup.new.json
species-vernacular-bulk-lookup.new.schema.json
species-vernacular-bulk-lookup.old.json
species-vernacular-bulk-lookup.old.schema.json

README.md

API Diff generator

Automatically generates a diff of old and new JSON / other documents.

View the current generated documents at https://atlasoflivingaustralia.github.io/bie-api-changes.

JSON diffs are provided by jsondiffpatch JS library entirely on the client side, others by the diff command line tool thendiff2html on the client side.

JSON diffs try to be smart about arrays - if an array entry has a 'guid', '_id', 'id' or 'name' property, then that array elements 'identity' is tracked by that value. This means that if array entries have changed index it can be shown in the diff. Of course, if a GUID has changed then it appears like the whole object has changed (ie the entire array entry block will be in red and struck through with a replacement block that may or may not have different values for non-guid properties).

New and old BIE base URIs are currently hard coded for BIE in generate.groovy.

Individual services are configured in config.json. To add notes for a diff, create a file $NAME.notes.md where $NAME matches the name in config.json.

All $NAME.[new|old].[json|csv] files are downloaded from the respective service and saved to the file system.

All $NAME.html pages are generated from a corresponding details.$type.html.ftl FreeMarker template. The details HTML pages are missing the Atlas branding as it messes with the diff styling. $NAME.notes.html pages are just the $NAME.notes.md Markdown rendered to HTML with Atlas branding. The Markdown notes will also appear in the $NAME.html page if they exist.

To update pages

Run ./generate.groovy. Use --skip to avoid downloading any JSON/CSV that already exist on the filesystem. Use --watch to watch all templates and the config file for changes and then regenerate the pages. Eg ./generate.groovy --skip --watch

Use npm install -g http-server to install a simple local HTTP server then http-server in this directory to serve files locally on http://localhost:8080/.

When you are satisified with changes to your local pages, git add . && git commit -m "your message" && git push to deploy to the gh-pages branch and update the https://atlasoflivingaustralia.github.io/bie-api-changes content (which are one and the same).