Accessing the DigitalNZ API
Posted on 13 December 2021 by James Robertson
We have recently made two changes to the way people authenticate with the DigitalNZ API.
Image from Te Papa (AR000627/568). CC BY-NC-ND.
Keyless entry
The first, and hopefully the most impactful change, was to remove the requirement for an API key (secret ID) to access public data. This means that anyone can query our API and retrieve structured, open data for individual records or a collection of records (search).
We hope that this change will further lower the barrier to reuse of the data we collect, making it easier still for Digital Humanities researchers, and other curious bods, who want to ‘play’ with the API and discover its value to them. This in turn may encourage more people to dig deeper and possibly even develop new applications or websites to utilise the data.
Try it for yourself! (You’ll enjoy the experience much more in Firefox, which will present the results in a friendly fashion.)
See our full metadata for the ‘key’ image used in this post: https://api.digitalnz.org/records/30704132
Search one of our new Content Partners for items from the 1940s:
https://api.digitalnz.org/records?text=&and[content_partner]=Te Toi Uku, Crown Lynn & Clayworks Museum&and[decade]=1940
Or find out how many times the word 'moustache' appears within DNZ content, broken down by content partner and decade:
https://api.digitalnz.org/records?per_page=0&facets_per_page=100&facets=content_partner,decade&text=moustache
Keys for busy users
However, a maximum query rate limit applies across all unauthenticated public requests. This rate limit is in place to protect the service from overuse, resulting in unsustainable costs, or potential attack. So, API keys are still available for use by regular, high volume consumers, or application developers, so that we can:
provide targeted help and support
increase query throughput (by negotiation)
notify of changes to the API
gather usage metrics to help improve the service.
Keeping keys secret
Which brings us to the second change we have made; passing API keys in the HTTP header instead of the request URL. This change improves the security and confidentiality of the API key transfer process. You can learn more about this change in API docs v3.
For now, we still support keys passed in the request URL. However, we plan to deprecate this feature in the middle of 2022. In the meantime, we will be doing our best to contact any affected users and help them transition to passing their key in the custom HTTP header, ‘Authentication-Token’.
Learn more
For more information about these changes, and our API in general, please see the Developers section of our website. And, as always, if you have any questions or feedback, please don’t hesitate to email us at info@digitalnz.org.
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.