Annotations API: Roadmap and Changelog

A roadmap for the development of the Annotations API along with a changelog of updates to the API.

The Annotations API will work towards a first major release at the third quarter of 2017. Until then, the Annotations API will feature many updates and iterations, which will be listed on this page.

Version 0.2.7 (May 2017)

In this release we have:

  • added support for the search profiles
  • adjusted pageSize limits for search to make them configurable and profile dependent
  • made several improvements to exception handling: responding with proper error codes and understandable error messages that can be configured through property files.
  • migrated the provider and user configurations to MongoDB.
  • revised the fields used for search and faceting, and fixed some issues.
  • fixed the PUT method to be less restrictive.
  • added support for asynchronuous indexing.
  • added support for canonical identifiers
  • added a method to support the update all references to record identifiers following changes in the main Europeana reference database
  • added support for write locks to the API for maintenance purposes.

Version 0.2.6 (December 2016)

In this release we have:

  • Removed the (Java) Exception class from error messages, all error messages only show what's happening in friendly ways now.
  • Updated the logic of the "generator" class in annotations. The minimised version (single value) can contain both a name or URI. The expanded version can contain an "id" (must be a URI) and/or "name" property.

Version 0.2.5 (October 2016)

In this release we mostly fixed some bugs:

  • Fixed a bug where the "items" listing in the search method did return a string for single-item results instead of a list.
  • Allowed Cross-Origin Domain requests to the Swagger API spec, to power the Annotations API console.
  • Added utf-8 headers to all JSON-LD output to ensure response is properly formatted.
  • Fixed a bug where requesting facets could return an exception.

Version 0.2.4 (October 2016)

In this release we've updated the API specification in line with the latest Candidate Recommendation release of the Web Annotations Protocol. This means that in the search method, many fields and structures have changed which are not backwards compatible. The good news is that since the latest protocol is a Candidate Recommendation, this should be the last Major change which breaks backwards compatibility.

  • Renamed the "contains" field to "items".
  • Add an "isPartOf" element to the search output to indicate information about the search result set with the total number of items ("total") and the URI of the search query ("id").
  • Changed the value of "type" to "AnnotationPage".
  • Added support for "next" and "prev" in the search output to indicate the URIs for the next and previous pages of search results (if applicable).
  • Added an "id" field to the search output with the URI of the search results (first page).
  • Renamed "totalItems" to "total" with the number of items on the current search result page (the total number of search results is in "total" in the "isPartOf" element.
  • To control the number of search results per page, use the "pageSize" parameter (defaults to 10).
  • To control the page (to paginate), use the "page" parameter, which defaults to 0 (first page).

Version 0.2.3 (August 2016)

In this release we have improved our search for annotations, which allows you to search for other fields than those were already available. We also updated some of the names of the search fields.

  • New: the ability to search for annotations based on the generator (id and name, fields: generator_id, generator_name).
  • Change: updated the fields for target_record_ids to target_id and motivation_key to motivation. This applies to both search & faceting.

Version 0.2.2 (July 2016)

With this release we further stabilised the Annotations API and addressed some feedback from the Alpha version. This version is a further iteration of the Public Alpha.

New features:

  • Support for geo-tagging, you can now submit geo-tags to the Annotations API for geographical information.

We've also updated our API to reflect the latest updates on the Web Annotation Model. Make sure to update your API clients accordingly:

  • The @ has been removed from all fields except for @context.
  • The simple tagging scenario without language information should use the bodyValue field to represent the tag. You can no longer send a literal as body anymore in this scenario.
  • The semantic tagging scenario does now accept a URI resource directly in the body field.
  • The annotation type has been updated from oa:Annotation to just Annotation.

Version 0.2.1 (March 2016)

First Public Alpha version of the Annotations API. Alpha means that the API is available for preview and testing. This also means that while the API is in Alpha changes can be and are likely to be made which are not backwards compatible.

  • First release.
  • Support for simple tags, semantic tags and object links.


The contents of the roadmap are subject to change, they will be updated at least every three weeks.

Major releases

Alpha release: February 2016
Beta release: Summer 2016
Stable release: Early 2017

In development
  • Enhancements to semantic tagging:
    • Support for more vocabularies.
    • Extracting and storing information from semantic resources (dereferencing).
  • Preparations for the Beta release:
    • Allow Europeana REST API keys to be used for the Annotations API.
    • Connect MyEuropeana API to the Annotations API for individual user management.
    • Automated registration of providers for annotations.
Planned development
  • Support for image (coordinates) annotations.
  • Support for time-based annotations (audio).
  • Support for geo-based annotations.
Along with the planned features every new release will aim to improve existing features, enhance existing types of annotations and to incorporate feedback from developers and users.