A summary of breaking changes in v3beta of the Trove API

trove-api-v3beta.md

Trove API v3 beta – summary of breaking changes

This is a work in progress as I work my way through the API changes. Additions are very welcome.

See the official release notes for more information. This summary only includes breaking changes – the things you'll need to change in your code before v2 of the API is switched off in early 2024. More documentation of the v3 API will be added over time to the GLAM Workbench.

The release notes don't mention the changes to the JSON responses. In general, the changes flatten the JSON responses by removing top-level wrappers that served no function. This means the way you access data within responses has changed. For example, assuming that you've saved the JSON response as a variable called data, to access the title of a newspaper article retrieved via the /newspaper/[article id] endpoint in version 2 you would use:

data["article"]["heading"]

While in version 3 you'd use:

data["heading"]

There are similar changes across all endpoints.

All endpoints

• change v2 to v3 in the endpoint url!
• callback parameter for JSONP removed, use CORS instead
• default encoding now JSON not XML

/result endpoint

• zone parameter has been replaced with category, possible values are: all, newspaper, magazine, image, research, book, diary, music, people, list; note that in most cases there is no one-to-one correspondence between zones and categories as the boundaries of what's included have changed, for example, the 'newspaper' category includes the contents of both the 'newspaper' and 'gazette' zones
• the handling of 'blank' searches has changed – in version 2 you could use a " " space as a value for q allowing you to search for everything, this doesn't work in v3beta, however, using the unicode null value, %00, does seem to work.
• JSON response format changes:
  • top-level response key removed
  • zone key changed to category
  • the meaning of the name parameter inside each category value has change – the old name value can be accessed via the code key, while name now returns the category's display name.

/work/[work id] endpoint

• JSON response format changes:
  • top-level work key removed

/newspaper/[article id] endpoint

• JSON response format changes:
  • top-level article key removed

/newspaper/titles endpoint

• JSON response format changes:
  • top-level response and records keys removed

/newspaper/titles/[title id] endpoint

• JSON response format changes:
  • top-level newspaper key removed

/list/[list id] endpoint

• JSON response format changes:
  • top-level list key removed – note too that in v2 list returned an array (even though there was only one value), in v3 there is just a single value, not an array; so instead of using data["list"][0]["title"] to get the title of a list, you'll need to use data["title"].

contributor endpoint

There are major changes here that aren't mentioned in the release notes. Previously a call to this endpoint without additional parameters just returned a long list of contributors. Now, you need to supply a q parameter to filter the results.

• q parameter added and required – to do a blank search and get all contributors (ie the v2 behaviour), include the q parameter with no value, eg: contributor?q=&encoding=json&reclevel=full
• JSON response format changes:
  • top-level response key removed

contributor/[NUC] endpoint

• JSON response format changes:
  • top-level contributor key removed