Introducing version 3 of the DigitalNZ API

Posted on 10 July 2012 by Thomasin

We recently made a series of changes to the technology that powers DigitalNZ, including introducing a new version of our developer API. The changes in the API combine requests made by developers with improvements we wanted to make use of in our own applications. The version 3 documentation is available on the developers section of DigitalNZ. We will continue to support version 1 and 2 of the API for the foreseeable future, but we encourage people to move existing applications to version 3 to take advantage of the many new features.

There most important changes in the Version 3 API are:

Speed

Version 3 is considerably faster than earlier implementations of the DigitalNZ API. This is perhaps the most significant overall change.

Standard response formats

Previous versions of the API presented results of Search Records query differently from a Get Metadata request. Version 3 of the DigitalNZ API uses a standard response format for all requests. XML outputted from a Search Records request will have the same structure as XML returned by a Get Metadata request

The "fields" parameter

Sometimes you may only want certain fields returned from an API call. For example you may only be interested in retrieving the "title", "creator", "content_partner" and "display_collection" for a particular search query. To restrict a response to just these fields, simply append to the end of your search request:

&fields="title,creator,content_partner,display_collection"

Easy results pagination

The DigitalNZ API allows developers to request up to 100 results per search. In earlier versions of the API, pagination was handled by keeping track of the index of items in search results. In version 3, simply specify how many results you want per page and then iterate through the pages.

For example, to get the fourth page of 25 results, append this to your search request:

&per_page=25&page=1

Returning multi-value entries in search

The first two versions of the DigitalNZ API had a quirk where a Search Records request would only return the first value from a multi-valued array. For example, if a record had three subjects, only the first subject would be returned. (Get Metadata requests on a single item always return the full result set.) This issue has been rectified in Version 3 of the API. JSON responses return an array of elements for multi-value fields; XML returns a series of tagged values.

I have started a thread on the Google Group to discuss the new API or you can contact me directly on develop@digitalnz.org. Please let us know what you think of the new version and feel free to ask any questions.

---

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.