This article provides user documentation for the Symplectic Elements API and provides your technical staff with the ability to fully integrate staff research data in either direction with any of the systems at your institution.

Some operations requiring an XML document in the request content offer a "validate" URL parameter for use during your development phase.

When set to "true", the API will validate your document against the API schema, and will return an argument fault (see the Error Codes section) and a meaningful XML schema validation error message in the response if your document does not validate when compared with the schema.

Making use of this parameter during development can help you to make sure your XML is in line with the expectations of the API while you are testing your code.

This XML validation functionality costs the Elements system significant resources, and must therefore not be used by your code once your client application has gone into production.

Not all API resources offer datasets about which the API can confidently know if the content has changed since you last accessed it, but some resources do offer standard HTTP cache control instructions (ETags and Last-Modified headers) to aid you in implementing more bandwidth friendly feeds, such as the individual /{category}/{id} resources.

See the individual operation descriptions for an indication of which of the ETag and Last-Modified caching instructions each operation supports, if any.

Please note that the usual operation success responses can of course be overridden in favour of an HTTP 304 (Not modified) in the case where you choose use HTTP cache control functionality.

Note: Standard HTTP endpoints will (regardless of rights assignments) grant minimum privileges to connecting agents, in line with tighter security standards. As such no data modification will be allowed and any resource requiring access rights will return a 403 (Forbidden) response. HTTP (unsecured) endpoint options are provided for testing purposes only.

Each API account comes with a set of rights. You can see the rights assigned to your API account by visiting the /my-account resource.

These rights are:

• whether your account has access to sensitive HR data.

• whether your account has access to staff research assessment data.

• whether your account is able to modify data in the Elements database.

Without the relevant rights, you may receive the standard "unauthorised access" API error response (with HTTP 403 - Forbidden) from some operations, and you may not receive back as much data as you might otherwise expect from other operations. This section describes exactly what behaviour you should expect from each of these rights.

Sensitive HR data is defined as the set of user generic fields numbered 11 upwards. Any data stored in these fields by your institution will not be visible to API accounts without this right.

All operations on the user feed resources /user-feed, user-feed/users/{proprietary-id} and /user-feeds/{feed-id} are inaccessible to API accounts without this right (always a 403 - Forbidden response), and all other operations that return a user object will not include any XML elements representing the user generic fields 11 and higher, even if the values exist in the database.

Research assessment data is defined as any data represented by the /ra-portfolios, /ra-portfolio and /ra-outputs resources.

All operations on these resources are inaccessible to API accounts without this right (always a 403 - Forbidden response). In addition, the ra-unit-id search parameter on the /users resource cannot be used without this right.

Data modification operations are all those operations whose HTTP method is not "GET" (namely, the "POST", "PUT" and "DELETE" operations). All of these operations will return the standard "unauthorised access" API error response (with HTTP 403 - Forbidden) if accessed from an API account without the right to modify data.

The Object Identifier Format is supported by many operations and enables you to identify objects in URLs in the way that best suits you. Not all of the operations support the format (e.g. user feed operations, where the user proprietary ID is the only user identifier of use). See the individual operation descriptions.

Example resource URLs supporting this format, with the Object Identifier Format part in bold are:

/relationships?involving=publication(500) searches for all relationships involving the publication with integer ID 500.

/relationships?involving=user(username-jdjones)&types=8&detail=full searches for all relationships involving the user with username "jdjones".

The general Object Identifier Format must include the category specification, and is: {category}({generalised-id})

For example, user(1) or publication(source-wos,pid-000256633300248).

A valid usage of such an identifier is highlighted in bold in the URL relationships?involving=publication(500).

Sometimes, the category is already specified in the URL immediately before the place holder for the identifier. In which case, the Object Identifier Format must exclude the category part (and its brackets), and just use the generalised-id part.

For example, the URL /users/username-jdjones gets the data for the user with username "jdjones". The bold part of this URL uses this abbreviated Object Identifier Format with the category part not specified.

Once the category of the object has been specified, to identify an object by its integer ID, just use the format {id}, where the {id} place holder is replaced with the numerical ID of the object. The same format can be used for any of the other categories. For example, the following full identifiers (including category) show examples using these integer IDs:

• activity(1)

• teaching-activity(18229)

• equipment(102)

• grant(2034)

• org-structure(76)

• project(45)

• publication(8)

• user(450)

In the context of users, to identify a user by their username instead of by their numerical ID, use the format username-{username} where the {username} place holder is replaced with the username of the user. Note that sometimes a user cannot be uniquely identified by their username alone, in which case the identifier is treated as not identifying any user.

For example, username-jdjones is a generalised-id for the user with username "jdjones".

To identify a user by a combination of their authenticating authority and their username, use the format authority-{authority},username-{username} where the {authority} place holder is replaced with the authenticating authority of the user, and the {username} place-holder is replaced with the username of the user. Note that the authority and username parts are separated by a comma.

For example, in the context of users, authority-internal,username-jdjones is a generalised-id for the user with authenticating authority "internal" and username "jdjones".

To identify an object via one of the records it contains, use the format source-{source},pid-{proprietary-id} where the {source} place holder is replaced with the name of the data source from which the record came, and the {proprietary-id} place holder is replaced with the proprietary ID of the record (the ID of the record as given to it by the data source). Note that the source and proprietary ID parts are separated by a comma.

For example, in the context of publications, source-wos,pid-WOS:000256633300248 is a generalised-id for the publication containing a record from the Web of Science with Thomson UT WOS:000256633300248.

To identify a user by their proprietary ID, use the format pid-{proprietary-id} where the {proprietary-id} place holder is replaced with the proprietary ID of the user.For example, in the context of users, pid-0036738 is a generalised-id for the user with proprietary ID "0036738".

Note: when using the /user/records/{data-source}/{proprietary-id} resource, {proprietary-id} refers to the id-at-source value in the following partial response, not the object proprietary-id value:

<api:object category="user" id="32" proprietary-id="30" authenticating-authority="Internal" username="rarnott" last-modified-when="2014-02-21T10:38:41.237+00:00" href="http://localhost:8091/elements-api/v5.5/users/32" created-when="2012-07-18T12:25:57.523+01:00" type-id="1" type="person">
  <!-- User type 1 is "person" -->
  ...
  <api:records>
    <api:record format="native" source-id="1" source-name="manual" source-display-name="Manual" id-at-source="AEDFBF5F-AD71-41CC-8B5C-24ED0BB82F6D">
  </api:records>
  ...

Operations that support the Object Identifier Format allow you to use your favourite way of identifying data when retrieving information about that data.

Response content is always either empty, or an ATOM feed. More details about the response feed for each operation is given in the Resources and Operations section.

Without exception, all ATOM-namespaced mark-up should be ignored when consuming the API from a client program.

ATOM content is provided to make it easy for a browser to generate a human readable summary of the information contained in an API response, as a list-based wrapper for detailed API response XML elements that will not appear in browsers or feed readers, and to encourage further development of the API to conform to a simple paginated list-based approach. 

Taking any programmatic dependence on the content of ATOM-namespaced elements in the API responses is not supported and is highly discouraged. All of the ATOM content is accessible in a more structured manner through embedded API-namespaced content.

The XML schema document provided with this documentation describes all of the API-namespaced request and response XML elements required and returned by the service, all of which belong to the namespace “https://www.symplectic.co.uk/publications/api”.  

The schema document contains in depth human readable annotations describing the meaning and use of many of the elements and attributes in the schema.

The schema's target namespace will likely not change as the API evolves. Rather the version number of the schema will change. The version number of the schema appropriate to this documentation is "5.5".

<xs:schema version="5.5" xmlns:api="https://www.symplectic.co.uk/publications/api" xmlns="https://www.symplectic.co.uk/publications/api" elementFormDefault="qualified" targetNamespace="https://www.symplectic.co.uk/publications/api" xmlns:xs="https://www.w3.org/2001/XMLSchema">

<xs:schema version="5.5" xmlns:api="http://www.symplectic.co.uk/publications/api" xmlns="http://www.symplectic.co.uk/publications/api" elementFormDefault="qualified" targetNamespace="http://www.symplectic.co.uk/publications/api" xmlns:xs="http://www.w3.org/2001/XMLSchema">

 The following pages show an example of a full ATOM document response from the API, with the API-namespaced content is prefixed with "api" and the ATOM-namespaced content greyed out.

GET resource: https://localhost:8091/publications-api/users?&detail=full&per-page=1

ATOM response:

<?xml version="1.0" encoding="utf-8"?>
<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>
  <category scheme="http://www.symplectic.co.uk/publications/atom/feeds/" term="item-list" label="Item list"/>
  <id>tag:publications@organisation,2009:/publications-api/feeds/objects?categories=users&amp;amp;per-page=1</id>
  <updated>2009-10-29T14:14:12.5471055+00:00</updated>
  <generator uri="https://pubs.symplectic.co.uk/" version="5.5">Symplectic Elements</generator>
  <icon>https://localhost:8091/publications-api/symplectic.ico</icon>
  <rights>This feed is the property of the Organisation, and can only be used with permission.</rights>
  <subtitle type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>
       This feed represents page <a href="https://localhost:8091/publications-api/objects?categories=users&amp;amp;per-page=1&amp;amp;detail=full">1</a> of 7 listing a total of 13 results from the following search query: <a href="https://localhost:8091/publications-api/objects?categories=users&amp;amp;detail=full">https://localhost:8091/publications-api/objects?categories=users&amp;amp;detail=full</a>
      </p>
    </div>
  </subtitle>
  <api:pagination results-count="13" items-per-page="1">
    <api:page position="this" number="1" href="https://localhost:8091/publications-api/users?per-page=1&amp;amp;detail=full"/>
      <api:page position="next" href="https://localhost:8091/publications-api/users?after-id=5&amp;amp;per-page=1&amp;amp;detail=full"/>
      </api:pagination>
  <link type="application/atom+xml" rel="self" href="https://localhost:8091/publications-api/ users?per-page=1&amp;amp;detail=full"/>
  <link type="application/atom+xml" rel="next" href="https://localhost:8091/publications-api/users?after-id=5&amp;amp;per-page=1&amp;amp;detail=full"/>
  <title>Symplectic Elements search results</title>
  <author>
    <name>Symplectic Elements at Organisation</name>
  </author>
  <entry>
    <id>tag:publications@organisation,2009:/publications-api/users/5</id>
    <category scheme="http://www.symplectic.co.uk/publications/atom/entries/" term="item" label="Item"/>
    <category scheme="http://www.symplectic.co.uk/publications/categories/" term="user" label="User"/>
    <updated>2009-05-28T14:54:08.937+01:00</updated>
    <link type="application/atom+xml" rel="alternate" href="https://localhost:8091/publications-api/users/5"/>
    <link type="application/atom+xml" rel="related" title="Relationships" href="https://localhost:8091/publications-api/users/5/relationships"/>
    <title>HOOK, Daniel</title>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>User</p>
        <p>
          <a href="https://localhost:8091/publications-api/users/5/relationships">Relationships</a> with other data
        </p>
      </div>
    </content>
    <api:object category="user" id="5" proprietary-id="3497" authenticating-authority="Internal" username="dwh" last-modified-when="2009-05-28T14:54:08.937+01:00 href="https://localhost:8091/publications-api/users/5" created-when="2005-07-28T15:46:18.377+01:00" type-id="1">
      <!--User type 1 is "user"-->
      <api:ever-approved>true</api:ever-approved>
      <api:is-current-staff>true</api:is-current-staff>
      <api:title>Dr</api:title>
      <api:last-name>Hook</api:last-name>
      <api:first-name>Daniel</api:first-name>
      <api:email-address>d.hook@institution.ac</api:email-address>
      <api:organisation-defined-data field-number="1" field-name="CID">Faculty of Natural Sciences</api:organisation-defined-data>
      <api:organisation-defined-data field-number="2" field-name="Faculty">Department of Physics</api:organisation-defined-data>
      <api:organisation-defined-data field-number="3" field-name="PrimaryHRO">Theoretical Physics Group</api:organisation-defined-data>
      <api:organisation-defined-data field-number="4" field-name="LowLevelHRO">South Kensington Campus</api:organisation-defined-data>
      <api:organisation-defined-data field-number="5" field-name="Campus">Huxley Building</api:organisation-defined-data>
      <api:organisation-defined-data field-number="6" field-name="Building">H/508a</api:organisation-defined-data>
      <api:organisation-defined-data field-number="7" field-name="Room">Research Fellow</api:organisation-defined-data>
      <api:organisation-defined-data field-number="8" field-name="PositionName"/>
      <api:organisation-defined-data field-number="9" field-name="Status"/>
      <api:organisation-defined-data field-number="10" field-name="Grading"/>
      <api:relationships href="https://localhost:8091/publications-api/users/5/relationships"/>
    </api:object>
  </entry>
</feed>

The XML in the above example is tightly controlled by the API schema and programmatic clients must restrict their dependence to it.

If any changes are made to the API-namespaced XML, then new documentation will describe the changes. But the non "api" prefixed XML is generated only for browsers and feed readers and is not to be consumed by API clients. Its content can change without notice during patches or upgrades to the system and without being documented.

All API-namespaced content will appear either at the ATOM feed-level or at the ATOM entry-level, with at most one API-namespaced content element inside each ATOM entry.

In this way, the API uses the ATOM format to wrap lists of elements inside ATOM entries, one ATOM entry for each API element in the list.

At the feed level, there will always be a schema-version element that lets you know which version of the API you are using.

This directly corresponds to the version of the schema for the response being made. In the above example ATOM response you will see:

<api:schema-version>5.5</api:schema-version>

There may also be other feed-level elements.

For example, for resources that represent collections of items, a pagination element describes the size of the results set and access to the next page. As in the above example ATOM response:

<api:pagination results-count="578" items-per-page="25">
  <api:page position="this"  href="https://localhost:8091/publications-api/users"/>
  <api:page position="next"  href="https://localhost:8091/publications-api/users?after-id=5"/>
</api:pagination>

The above example ATOM response wraps a single object inside each ATOM entry, but other responses will wrap other types of API element.

All of the operations are capable of returning an error response, instead of their usual response. 

For example, in response to the following GET: https://localhost:8091/publications-api/publications?userame=nonsense

<?xml version="1.0" encoding="utf-8"?>
<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>
  <category scheme="http://www.symplectic.co.uk/publications/atom/feeds/" term="error-list" label="Error list"/>
  <id>tag:publications@organisation,2009:/publications-api/last-errors</id>
  <updated>2009-10-29T14:28:55.9576745+00:00</updated>
  <generator uri="http://localhost/" version="5.5">Symplectic Elements</generator>
  <icon>https://localhost:8091/publications-api/symplectic.ico</icon>
  <rights>This feed is the property of the Organisation, and can only be used with permission.</rights>
  <subtitle type="xhtml">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>This feed describes the errors that occured during the processing of the last request.</p>
    </div>
  </subtitle>
  <title>Errors</title>
  <author>
    <name>Symplectic Elements at Organisation</name>
  </author>
  <entry>
    <id>tag:publications@organisation,2009:/publications-api/last-errors/1</id>
    <category scheme="http://www.symplectic.co.uk/publications/atom/entries/" term="error" label="Error"/>
    <updated>2009-10-29T14:28:55.9576745+00:00</updated>
    <title>Error: argument fault</title>
    <content type="xhtml">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>categories value not in the correct format.</p>
      </div>
    </content> 
    <api:error code="argument fault">username parameter does not apply to this operation.</api:error>
  </entry>
</feed>

The content of an error response is an ATOM feed where the first ATOM entry contains an API error element (and in this case all ATOM entries will contain an error element): 

<api:error code="argument fault">username parameter does not apply to this operation.</api:error>

The possible list of error codes is defined by the XML schema and discussed below. Note that in addition to the error XML returned, you should expect an HTTP error status code to be returned by the server as documented below. In some cases, where a request cannot get through to be executed by API code, you may receive only an HTTP error response.

In particular, if the content of your request contains badly-formed XML (for example, it contains illegal characters such as the vertical tab character at Unicode code point 0x0B) you will receive an immediate HTTP 400 response (Bad Request) before the API has a chance to start executing its application code. If there is a response with this HTTP code but no ATOM error feed then please verify your XML using a suitably configured XML parser.

The API error codes are described below. The HTTP status code returned with the response is also listed. Note that the HTTP status code is a less fine-grained indicator of the nature of the error than the application error code, but it can be very useful nonetheless.

HTTP 400 bad request

One or more of the query string arguments or request body elements is formatted incorrectly, or its value is inappropriate to the operation.

HTTP 409 - conflict

A concurrency conflict (or database deadlock) occurs when two concurrent operations attempt to access data that is being updated by one of them, and the progress of one of the operations is blocked (yours, in this case).

You should simply try the operation again. If this happens often, and you are yourself running concurrent operations, you should either arrange for the concurrent operations to operate on unrelated data, or you should execute your operations serially.

If you are not running concurrent operations yourself, then it is likely that the system administrator has scheduled a heavy data-update operation for the same time as your operations, and it is operating on the same data. You should liaise with the system administrator to adjust the timing of your operations to avoid the conflicts.

HTTP 504 - gateway timeout

A database timeout occurred while attempting to process the request.

This may be due to high server load or simply due to a sudden increase in database activity after a period of idling. Your program may just need to try the operation again once the server has had a few seconds to warm up, or you may need to reduce load by providing the server with a few seconds recovery time at more frequent intervals.

In any case, when writing a client to consume the API, you should build in robustness against database timeouts (by for example implementing a simple exponential back-off strategy) before giving up and reporting an error.

If the timeouts seem to occur at the same time of day each day, they are probably caused by regular server maintenance operations such as database backup plans. You should avoid contact with the system at such times.

If you have a choice, do not force a high server load during office hours as this will heavily impact on the performance of the system at a time when it is needed by the user-interface, which competes for resources with the API.

Remember to liaise with the application administration team to schedule your use of the system.

HTTP 401 -unauthorised

The credentials you supplied were invalid or missing, or the IP address of your machine has not been registered with the Elements system. Please contact the system administrator to make sure the credentials you are using are present and correct, and that your IP address is registered. Also check that you are submitting the credentials in the correct way. See the Security section.

If you are sure the credentials are correct, then have the system administrator check the API's log files for a confirmation of why you cannot access the API. The system administrator will need to look up the exact time of your requests in the log, so make sure you make a note of them.

HTTP 410 - gone

You have requested a resource whose permanent deletion has been logged.

HTTP 404 - not found

You have requested a resource that does not exist in the Elements System.

HTTP 500 - internal server error

An error occurred in the server. If retrying the operation does not solve the issue, please contact your Elements System administrator, who will be able to look up the details of the error in the system log. Please inform the system administrator of the exact circumstances of the error, including its time.

HTTP 403 - forbidden

The account to which you have authenticated does not have the rights to perform the operation you are attempting. You must contact the system administrator for the Elements System to elevate the permissions associated with your account.

If you find that you are perfectly well able to read data from the API using the various GET-based requests, but that you are unable to execute the POST/DELETE or PUT-based operations to write data to the Element System, then your account needs to be registered at a higher privilege level in the Elements System. Please ask the system administrator to allow your account write-access to the Elements database.

HTTP 403 - forbidden

The Elements System supports a modular licensing model. If your institution has not licensed functionality required to service a particular operation request, you will receive this error code.

In normal operation, most responses will be success responses, in the HTTP 2xx range, or very occasionally a 303 (see other) redirect, which itself should return in the HTTP 2xx range. A successful response does not preclude the possibility that the operation completed with problems.

Where an operation was completed successfully, but some warnings were generated, such warnings are included in API namespaced elements within each of the ATOM entries.

<api:warnings>
   <api:warning associated-field="isbn-13">Failed to parse valid ISBN-13 from \"0123456789\".</api:warning>
</api:warnings>

These warnings represent human readable messages suitable for you to log and review by eye should you need to. Where a warning corresponds to a bibliographic record field, the field name is also provided.

Resources supporting the page query parameter are implemented as paginated ATOM feeds. All paginated resources offer pagination control and information in the same format and offer navigation of the pages in the same way.

At the feed-level, an API pagination element is returned:

<api:pagination results-count="578" items-per-page="25">
   <api:page position="this"  href="https://localhost:8091/publications-api/grants"/>
   <api:page position="next" href="https://localhost:8091/publications-api/grants?after-id=25"/>
</api:pagination>

Most of this is self-explanatory. To navigate to the next page, follow the indicated link. The total number of results and the number of items per page are all made available. The next page elements will not appear if there is not a next page of results.

To alter the number of results per page, supply an additional "per-page" query parameter with the required number of items per page as its value. Supplying a value greater than 1000 is an error, and where possible you should keep to a reasonably low a value in order to reduce server load. If using a full detail response level (i.e. /grants?per-page=25&detail=full), a maximum "per-page" value greater than 25 is an error.

Note that some resources that represent collections are not paginated, and for these you will receive no element in the response.

Some resources offer control over how much detail is included in the response. The /publications resource by default returns lists of references to publications, and the /{categories}/{id} resources (e.g. /publications/12) in contrast by default returns the full details of the object that the resource represents.

For resources that offer control of detail level, a "detail" query parameter can be used to override the default behaviour of the resource.

The value of the detail parameter should be one of "ref" and "full", according to whether you want abridged reference-style information or full data.

For example, if you are interested in overriding the default behaviour of the /users resource to return lists of users instead of lists of user identifiers then use /users?detail=full.

An example user returned with reference-level detail (detail="ref") looks like this:

<api:object category="user" id="5" proprietary-id="3497" authenticating-authority="Internal" username="dwh" last-modified-when="2009-05-28T14:54:08.937+01:00" href="https://localhost:8091/publications-api/users/5" created-when="2005-07-28T15:46:18.377+01:00" type-id="1"/>

The same user returned with full-level detail (detail="full") looks like this:

<api:object category="user" id="37674" authenticating-authority="Internal" username="sutherland" last-modified-when="2009-03-30T16:55:56.577+01:00" href="https://localhost:8091/publications-api/users/37674" created-when="2009-02-23T13:16:13.54+00:00" type-id="1">
  <!--User type 1 is "user"-->
  <api:ever-approved>true</api:ever-approved>
  <api:is-current-staff>true</api:is-current-staff>
  <api:last-name>Sutherland</api:last-name>
  <api:email-address>m.sutherland@institution.ac</api:email-address>
  <api:organisation-defined-data field-number="1" field-name="CID"/>
  <api:organisation-defined-data field-number="2" field-name="Faculty"/>
  <api:organisation-defined-data field-number="3" field-name="PrimaryHRO"/>
  <api:organisation-defined-data field-number="4" field-name="LowLevelHRO"/>
  <api:organisation-defined-data field-number="5" field-name="Campus"/>
  <api:organisation-defined-data field-number="6" field-name="Building"/>
  <api:organisation-defined-data field-number="7" field-name="Room"/>
  <api:organisation-defined-data field-number="8" field-name="PositionName"/>
  <api:organisation-defined-data field-number="9" field-name="Status"/>
  <api:organisation-defined-data field-number="10" field-name="Grading"/>
  <api:relationships href="https://localhost:8091/publications-api/users/37674/relationships"/>
</api:object>

A response at reference-level detail will only promise to return the top level element and its attributes, whereas a response at full-level detail will return all available data for the object.

API responses include three timestamp for of any objects included in the response. These are: create when, last modified, and last affected when

You can use your knowledge of how up-to-date the data you have pulled out of the API is to help you implement differentially updated caches of data by submitting queries to the API to only return data since a specified time. This approach can save a lot of bandwidth and I/O resource.

Note: The "last affected when" timestamp is only available in v5.5 and above endpoints. In older endpoints, the "modified" timestamp returned "affected" objects. In other words, the behaviour of filtering on "modified" has changed to return fewer objects, and "affected" has been added to capture previous behaviour.

The definition of when an object is considered "modified" is as follows:

• Any of its own values are changed

• A new record is added to the object

The definition of when an object is considered "affected" includes all of the "modified" events as well as:

• Any relationship or relationship suggestion involving the object has any of its values changed

• Any of the objects directly related to the object by a relationship or a relationship suggestion has any of its values changed

• Any new relationship or relationship suggestion involving the object is created

• Any relationship or relationship suggestion involving the object is deleted

The definition of the affecting of an object is quite broad, considering an object affected if any of its immediately related neighbours has any of its data values directly changed or if its list of relationships or relationship suggestions changes in any way.

Together with the ability of the API to list objects changed since any particular time of your choosing, this allows you for example to confidently know when to update your cached publication lists. If a user has authored a new publication since you last cached your publication list, you can rely on the author appearing as an affected user in the API the next time you check in looking for changes.