Changes between API v5.5 and v6.13

This article enumerates the backwards breaking changes between the Elements v5.5 and v6.13 API endpoints.

For those wishing to migrate between endpoints, each of the listed changes should be considered.

Note: In line with our standard processes, the previous v5.5 API will be supported for use for two years from the date of this release. We know that for many of you, it can take some time to update existing integrations, so we do recommend that you plan your transition well in advance of the end of support date.

The following backwards breaking changes have been made:

• ATOM markup removed

• Groups category now treated as objects -

• Existing groups migrated to legacy-groups

• Privacy level available when importing relationships

• is-visible element removed from relationships

• user profile field privacy level 'limited' renamed to 'private' - importing 'internal' now supported

• category types reporting-dates element removed

• import-user-relationship removed

Examples of these changes may be found in the v6.13 Postman Collection.

The latest v6.13 xsd schema is also available.

All xml returned in a response will now belong to the xmlns:api="http://www.symplectic.co.uk/publications/api" namespace and any ATOM markup has been removed. This change results in smaller results and a slightly modified structure. All responses will now contain api:response at the top level.

For paginated reponses, the path to select an object will now be api:response/api:result-list/api:result/api:object. Previously the path would have been feed/entry/api:object.

For example, a v6.13 paginated response:

<api:response xmlns:api="http://www.symplectic.co.uk/publications/api">
  <api:version uri="https://localhost:8080/" elements-version="6.14.0.0" schema-version="6.13" product-name="Elements Demo"/>
  <api:request href="https://localhost:8091/secure-api/v6.13/publications"/>
  <api:pagination results-count="28" items-per-page="25">
    <api:page position="this" href="https://localhost:8091/secure-api/v6.13/publications"/>
    <api:page position="next" href="https://localhost:8091/secure-api/v6.13/publications?..."/>
  </api:pagination>
  <api:result-list>
    <api:result>
      <api:object category="publication"> ...

vs a v5.5 paginated response:

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:api="http://www.symplectic.co.uk/publications/api">
  <api:schema-version>5.5</api:schema-version>
  <api:pagination results-count="49258" items-per-page="25">
    <api:page position="this" href="https://localhost:8091/secure-api/5.5/publications"/>
    <api:page position="next" href="https://localhost:8091/secure-api/5.5/publications..."/>
  </api:pagination>
  <link type="application/atom+xml" rel="next" href="https://localhost:8091/secure-api/5.5/publications..."/>
  <link type="application/atom+xml" rel="self" href="https://localhost:8091/secure-api/5.5/publications"/>
  <entry>
    <api:object category="publication">...

For single item results, the path will now be api:response/api:result/{item}. The v5.5 response path for the same item would be feed/entry/{item}.

Note that the item within an api:result (previously an atom:entry) will remain unchanged, unless otherwise noted below. The api:pagination element remains unchanged as well.

Further detail about the change in xml structure can be see in v6.13 Requests and Responses.

Groups are now treated as objects within the API, and are available to any resource which accepts a category and id. For example, GET /groups/{id} or PATCH /group/records/manual/{id}.

The /groups operation now retrieves a paginated list of group objects, defaulting to 25 per page.

Operations available to other categories are now available to groups, such as updating privacy level, changing type, and modifying metadata fields. Note that groups, much like users, cannot be created or deleted via the API, only retrieved and modified.

To ease migrations, the v5.5 /groups resource has been renamed /legacy-groups and returns the same list of api:user-group results.

The is-visible flag has been removed from relationships and the effective-privacy-level should be used by consumers instead, with values of public, internal, or private.

Furthermore, privacy-level may now be set when importing relationships, allowing for public, internal, or private privacy level to be declared. In v5.5, only an is-visible flag was available. This flag has been removed.

Existing uses of the is-visible flag should now set a privacy-level.

For example, in v5.5:

<import-relationship xmlns="http://www.symplectic.co.uk/publications/api">
  <from-object>publication(1000)</from-object>
  <to-object>user(32)</to-object>
  <type-name>publication-user-authorship</type-name>
  <is-visible>false</is-visible>
</import-relationship>

And the new v6.13 approach:

<import-relationship xmlns="http://www.symplectic.co.uk/publications/api">
  <from-object>publication(1000)</from-object>
  <to-object>user(32)</to-object>
  <type-name>publication-user-authorship</type-name>
  <privacy-level>Private</privacy-level>
</import-relationship>

The limited privacy level on user profile fields has been renamed to private to bring it in line with other uses of privacy in the system. The internal privacy level is now supported on fields and field items.

For example, users may set items to private and internal when calling PATCH /user/records/manual/{pid}:

<update-record xmlns="http://www.symplectic.co.uk/publications/api">
  <fields>
    <field name="personal-websites" operation="add">
      <web-addresses>
        <!-- The internal privacy level is now supported -->
        <web-address privacy="internal">
          <url>http://figshare.com/authors/Jonathan_Breeze/275550</url>
          <type>figshare</type>
        </web-address>
        <!-- N.B. The 'limited' privacy level has been renamed to 'private'
        <web-address privacy="limited"> -->
        <web-address privacy="private">
          <url>http://www.mendeley.com/profiles/jonathan-breeze1/</url>
          <type>mendeley</type>
        </web-address>
      </web-addresses>
    </field>
  </fields>
</update-record>

The reporting-dates field has been removed from the /{category}/types resource and users should use the existing reporting-date-fields element instead.

Support for the import-user-relationship element has been removed from the POST /relationships operation. Callers should use the existing import-relationship.