Updated API documentation
Posted on 10 February 2021 by Dan
One of the strongest pieces of feedback from last year’s API survey was that we needed to improve our API documentation and support. This didn’t come as a surprise and was already on our backlog of work — but it was good motivation to finally get it done.
New OpenAPI specification on SwaggerHub
This is the most comprehensive set of API docs we’ve ever had! It includes fields, tips, and tricks that never made it into the original documentation. This new DigitalNZ OpenAPI specification shows how to use wildcards and boolean logic in basic searches (*, -, OR, AND) as well as a bunch of new fields including ‘has_large_thumbnail_url’ and ‘has_lat_lng’. The OpenAPI specification also shows some example XML and JSON responses.
OpenAPI specifications are a widely adopted, language-agnostic standard for documenting and defining APIs. They allow both humans and computers to discover and understand the capabilities of an API.
Existing API documentation refresh
New API examples and demo code
We're also grateful to be able to share some awesome new Jupyter notebook resources created by Tim Sherratt. They provide informative tips, tools, and examples that cover a wide range of really interesting interactions with the DigitalNZ API. Kia ora Tim!
Jupyter notebooks are a combination of narrative text and live code in an environment that encourages you to learn and explore. The resources run in your browser and allow you to play with the code without installing any software.