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.

Screen grab of SwaggerHub information — https://app.swaggerhub.com/apis-docs/DigitalNZ/Records/3#/

Read the new OpenAPI specification on SwaggerHub

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.

Read the new OpenAPI specification on SwaggerHub

Existing API documentation refresh

We also took the opportunity to spruce up our existing API documentation and developer pages so that they’re easier to navigate and learn the basics of working with the API.

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!

Read the DigitalNZ Jupyter notebooks here

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.

We've turned off comments here, but we'd still love to know your thoughts. Visit us on our Facebook Page @digitalnz or on Twitter @DigitalNZ to share any ideas or musings with the DigitalNZ team.