Together with the accompanying XML schema, the linked articles provide 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.

By default, the API is implemented as a secure REST style web service serving xml documents over HTTPS at an endpoint address defined by your institution.

Much of the human readable documentation for the details of request and response content is contained within the accompanying XML schema document. Don't forget to consult this document when interpreting response content or crafting requests.

For the examples in this documentation, the API endpoint address will be https://localhost:8091/elements-api. Replace this with the endpoint address in use at your institution. If you are using an unsecured endpoint, remember the address will start with 'http', not 'https'. All relative URIs in this document will be relative to this endpoint base address.

Important! Your system administrator may not have enabled an unsecured endpoint. Symplectic highly recommend using secure connections for all API connections to maintain data security.

The API is designed to allow your institution to implement a nightly user feed to keep the list of users of the system up-to-date, to allow you to implement a regular feed of research data from any of your systems into the Elements system, and to allow your external systems to search for and cache comprehensive and verified research data for their own purposes.

Such data can for example then be served by your institution's professional web page system, making your research data constantly available to the world.

The API is not designed to expose the Elements system as a high throughput real-time data server in a performance-critical role (for example, real-time provision of page data as part of a highly responsive web page system). To achieve this goal, implement an appropriate caching solution in front of the Elements system.

When exporting data from the API, it is your responsibility to ensure that use of the exported data aligns with the privacy policy of your institution - and in particular that you are not exposing exported data to unauthorised individuals. This includes the need to:

• Review the data that you plan to use for its level of privacy (please see the Introduction to Data Privacy and Personal Data in Elements for an overview of data privacy in Elements, and the relevant API Schemafor how data with a configurable privacy level is represented in API responses);

  • An example is to observe the privacy-level="public"|"internal"|"private" attribute on publication to user relationships. A user who has marked their relationship with a publication as private will expect you not to expose their relationship with the publication on a public-facing website.

  • When importing user relationships, pay attention to whether you should set an appropriate value on the privacy-level="public"|"internal"|"private" attribute. As documented in the API schema, be aware that setting privacy-level="internal" on a relationship between two research objects such as a user and a publication does not make either the user or the publication themselves invisible in any context, it just determines the visibility of the relationship between them. The related objects are still typically independently discoverable in system search and in others places throughout the Elements user interface.

• Ensure that the individuals to whom you intend to expose extracted data are all authorised to do so by your institution.

By default, the API is configured to reject calls from unauthenticated clients. Authentication is implemented using the simple HTTP Basic authentication method (over a secure TLS channel), and authorisation to view or modify data is granted according to the rights associated with your credentials. Each and every call to the API needs to submit valid credentials in the appropriate way.

In addition, the API is configured to reject calls from all but a specified list of allowed client IP addresses, so you should contact the system administrator at your institution to arrange for appropriate access to the API for your system, by registering your IP address and finding out and using your credentials during requests.

Without properly authenticating, you will only receive HTTP 401 Unauthorised responses.

Alternatively, your system administrator may choose to expose an unsecured API endpoint. In this case, authentication will not be required (and indeed, you should avoid supplying credentials to an unsecured endpoint, as they will be sent in the clear via HTTP).

You must also arrange with the system administrator the manner of your planned use of the API, as they may for example wish to have you avoid placing undue stress upon the system during office hours, when the Elements database is typically required to be responsive for its user-interface.

Other considerations may include avoidance of coincidence with database backup schedules and heavy usage of the Elements database by other systems.

When writing code to consume the API, do not make calls so frequent that the Elements System becomes the bottleneck for speed of data-transfer.

If your program is pulling data as quickly as it can, then it is placing too heavy a burden on the Elements System. A simple policy of regular breaks in processing will allow the system time to recover from heavy queries. Make your application sleep between receiving a response and issuing its next request. A starting value of 500ms may be appropriate.

Any request to a secure API endpoint that does not supply authentication credentials will return a response with a 401 (Unauthorized) code and empty content, as well as a WWW-Authenticate header prompting you to reissue your request with HTTP basic access authentication credentials.

For the interested, see https://en.wikipedia.org/wiki/Basic_access_authentication for a summary of HTTP basic access authentication.

The 401 response and WWW-Authenticate response header sent back by the API are well understood by browsers, which in turn will offer the user a login dialog before reissuing the original request for you with the supplied credentials attached. Your browser will then usually remember your credentials and resubmit them for you on each subsequent request while you browse the API's resources.

In the case of your programmatic client however, it must submit its credentials (username and password) by supplying its own "Authorization" request header with a value generated by the following steps:

1. Create a text string consisting of the username followed by a colon followed by the password e.g. "username:password".

2. Encode this string to a byte array using UTF-8.

3. Convert the byte array to its base 64 text encoding.

4. Append the base 64 encoded credentials to the text "Basic " (note the trailing space).

This authentication does not begin a session and does not return any cookies to your client. You are simply required to provide your credentials anew on every request.

If your credentials are for some reason invalid, you will receive a 401 (Unauthorised) response.

A successfully authenticated request may also return a 403 (Forbidden) response, if your account does not have the rights to perform the operation you are attempting.

To see the permissions associated with your account, use the /my-account resource.

If you have problems authenticating, see the Troubleshooting section.

Please note that although passwords are sent "in cleartext", in the normal running of the system they are sent only over a secure connection (HTTPS), and so are entirely safely transmitted.

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. 

When accessing the /my-account resource on an unsecured endpoint, you will see the details for an anonymous account.

You must not send a username and password to an unsecured endpoint: they will be sent in cleartext over a standard HTTP connection, and will not be secure.

Your integration with the API is a form of custom integration with Elements. Please see the following support articles for a discussion of topics related to the maintenance of any custom integration:

• Introduction to Custom Integrations

• Ongoing maintenance of customisations and custom integrations : Symplectic Support

These articles include information about the maintenance of your custom integration when upgrading Elements, and details your options when migrating a self-hosted instance of Elements to the Cloud.

Elements provides a simple mechanism for you to access older versions of the API in order to allow you a period of grace during which your legacy client can continue to work with the system while you perform upgrade work.

Older compatibility endpoints (versions) of the API can be served from the latest version of Elements if your administrator so wishes. For example, to continue to use the v5.5 API functionality, contact your system administrator and ask for the legacy API base URL for that endpoint. This might be https://localhost:8091/elements-api/v5.5. Then you should work with the v5.5 API documentation.

You must reconfigure any clients written for interoperation with older versions of the API to the appropriate legacy endpoint for them to continue to use the system without needing to make any code changes. However, consuming a legacy endpoint will mean that you continue to have access only to legacy functionality. In some cases this means that new types or fields of data may be hidden, or appear slightly modified in order to be communicable while still respecting the older API's XML schema.

You must of course access the endpoint for the latest version of the API in order to perform operations introduced by the latest version of the system.

Each object in the Elements database corresponds to one real-world research-related object, process or activity. Elements can store objects belonging to the following categories:

• publications

• grants

• professional activities

• organisational structures

• projects

• pieces of equipment

• users

• teaching activities

• funding bodies

• records of impact

• journals

• deposit advice

• groups

Relationships between objects are described by semantic links. A large number of possible links can exist between the objects in the system. For example, a user may be linked to a publication as an author, editor, contributor or translator.

The Publication category is further divided into types of publication. The default publication types installed with Elements are:

• artefact

• book

• chapter

• composition

• conference

• dataset

• design

• exhibition

• figure

• fileset

• internet publication

• journal article

• media

• other

• patent

• performance

• poster

• presentation

• report

• scholarly edition

• software / code

• thesis / dissertation

If these default types do not cover the needs of your institution, you can define custom publication types to extend this list.

Grants are awards of or applications for funding. By default, there is only one grant type in Elements. You can define more grant types if you need to.

Professional Activities is a wide category, covering activities, duties and roles that did not have a publication or teaching output, but warrant recording in a user's profile. The default types are:

• broadcast interview

• committee membership

• community service

• conference reviewing / refereeing

• consulting / advisory

• distinction

• editorial

• employee supervision

• event administration

• event participation

• expert witness

• fellowship

• grant application assessment

• institutional review

• journal reviewing / refereeing

• membership

• non-research presentation

• office held

• promotion / tenure assessment

• text interview

If these default types do not cover the needs of your institution, you can define custom professional activity types to extend this list.

Each organisational structure object might represent a department or faculty in your institution, or a department or faculty within an external body, or might represent an external body itself. By default, there is only one type of organisational structure in Elements.

Note: organisational structure objects are are not related to the User Groups that you create to manage users within Elements.

A project, like any other object, might share any number of relationships with other objects. For example, a grant may fund the project, or a user may be a manager of the project.

The default equipment types are:

• database

• instrument

• service

• software

There are several possible links between a piece of equipment and other objects. For example, users may be linked as a manager of the equipment, or grants may be linked as funding it.

Each user object represents a user of the system, past or present. The User category is a specialised category that is crucial to Elements.

There is only one user type and you cannot add new types. The data structure of users is also more fixed than for other categories (there are however 'generic' data fields provided to capture data that is specific to your institution). Your institution controls the list of users in the in a number of ways: automatically, by providing user feeds through this API, and manually, using the administrative tools available in the web application. See the HR Data Import and Elements User Groups article for more information.

The Teaching Activities category captures a user's contribution to the teaching output of an institution. The default teaching activity types are:

• course developed

• course taught

• course-based degree supervision

• graduate examination

• mentoring

• program developed

• research-based degree supervision

If these default types do not cover the needs of your institution, you can define custom teaching activity types to extend this list.

Each group object represents a current group in the system. The Group category is a specialised category in Elements. At least one top level group is always present in the system. 

Groups cannot be created or deleted via the API, but some update operations are available.

Because research data can enter the system from more than one data source, each object (excluding users) has the ability to store as many independent metadata records (each representing the very same object) as there are data sources from which the object's metadata has been discovered/imported. This is a central feature of the Elements system, and is one the foundations upon which its disambiguation functionality works.

For example, a publication may contain three records, one from the Web of Science, one from PubMed, and one from the Manual data source (representing data that has been typed in, or imported from file, by a user of the system). Each of these three records independently represents the same publication. They are stored together within the same publication object.

Each category (excluding users) distinguishes between one or more types of object within the category. For example, a publication object could be of type "book" or "journal article".

The definition of a type includes a complete specification of the fields stored in the database for each instance of the type, and your institution has a degree of control over the set of types for each category and the settings for each type definition.

The API offers resources for you to interrogate the definition of these types so that you can be aware of the fields stored for each type of object within each category. For example, the /publication/types resource represents the publication types configured in the system, and lists the data fields used by those types.

Your institution might decide to alter the definition of any of the types in the system, perhaps adding a new field called "Comments" to the patent type of publication, for example. All patents stored in the Elements database will then have a "Comments" field whose value will be immediately available to you through the API.

The following extract from an API response shows some of the fields of the "artefact" type of publication.

<api:type id="12">
  <api:heading-singular>Artefact</api:heading-singular>
  <api:heading-plural>Artefacts</api:heading-plural>
  <api:heading-lowercase-singular>artefact</api:heading-lowercase-singular>
  <api:heading-lowercase-plural>artefacts</api:heading-lowercase-plural>
  <api:fields>
    <api:field>
      <api:name>title</api:name>
      <api:display-name>Title</api:display-name>
      <api:type>text</api:type>
      <api:is-mandatory>true</api:is-mandatory>
    </api:field>
    <api:field>
      <api:name>abstract</api:name>
      <api:display-name>Abstract</api:display-name>
      <api:type>text</api:type>
      <api:is-mandatory>false</api:is-mandatory>
    </api:field>
    <api:field>
      <api:name>authors</api:name>
      <api:display-name>Authors</api:display-name>
      <api:type>person-list</api:type>
      <api:is-mandatory>true</api:is-mandatory>
    </api:field>
    <!--more fields-->
  </api:fields>
</api:type>

If your institution makes changes to the type definitions in the Elements System, you may need to update any client programs that you have written that consume API data. Make sure you and your system administrator are in dialogue about any type changes planned by your institution.

As mentioned, each object (excluding users) is capable of containing as many records representing the same object as there are registered sources from which the system gets its data. Each record independently represents the object's metadata as imported from the respective data source. The Elements system always knows where each record came from.

For example, your institution might have the following publication data sources configured, and each publication will then contain zero or more records sourced from each of them: arXiv, DBLP, manually-entered, PubMed, Scopus and Web of Science.

The Elements System does allow for multiple records from the same data source to represent the same object, but only for some sources.

When you consume the data for a publication through the API, you are able to choose which record best suits your needs. If you prefer the data from PubMed, you are free to use it if it is present. You might prefer to use all of the records in some way. You might choose the record declared as the "preferred record" of one of the publication's authors.

The choice is yours. If you prefer not to deal with the hassle of multiple records, you can always just read the first one.

All objects will have at least one record (except for users, whose data is represented slightly differently to the other categories).

Here is an example publication with multiple records retrieve via the Elements API. Note that for the sake of brevity we have stripped out all of the fields except for authors and titles.

The "authors" and "title" fields are defined by the type 5 publication (the "journal article" type). The type of the publication is indicated by the "type-id" attribute on the api:object element.

<api:object category="publication" id="15" last-modified-when="2009-05-28T14:54:08.937+01:00" href="https://localhost:8091/publications-api/publications/15" created-when="2006-07-05T00:20:20.833+01:00" type-id="5">
  <!--Publication type 5 is "journal article"-->
  <api:ever-approved>true</api:ever-approved>
  <api:reporting-date-2>1986-04-11</api:reporting-date-2>
  <api:records>
    <api:record format="native" source-id="3" source-name="wos" source-display-name="Web of Science" id-at-source="A1986C172200006">
      <api:citation-count>25</api:citation-count>
      <api:verification-status>verified</api:verification-status>
      <api:native>
        <api:field name="authors" type="person-list" display-name="Authors">
          <api:people>
            <api:person>
              <api:last-name>GRESTY</api:last-name>
              <api:initials>M</api:initials>
            </api:person>
            <api:person>
              <api:last-name>BRONSTEIN</api:last-name>
              <api:initials>A</api:initials>
            </api:person>
          </api:people>
        </api:field>
        <api:field name="title" type="text" display-name="Title">
          <api:text>OTOLITH STIMULATION EVOKES COMPENSATORY REFLEX EYE-MOVEMENTS OF HIGH-VELOCITY WHEN LINEAR MOTION OF THE HEAD IS COMBINED WITH CONCURRENT ANGULAR MOTION</api:text>
        </api:field>
        <!--other fields-->
      </api:native>
    </api:record>
    <api:record format="native" source-id="2" source-name="pubmed" source-display-name="PubMed" id-at-source="3714102">
      <api:verification-status>verified</api:verification-status>
      <api:native>
        <api:field name="authors" type="person-list" display-name="Authors">
          <api:people>
            <api:person>
              <api:last-name>Gresty</api:last-name>
              <api:initials>M</api:initials>
            </api:person>
            <api:person>
              <api:last-name>Bronstein</api:last-name>
              <api:initials>A</api:initials>
            </api:person>
          </api:people>
        </api:field>
        <api:field name="title" type="text" display-name="Title">
          <api:text>Otolith stimulation evokes compensatory reflex eye movements of high velocity when linear motion of the head is combined with concurrent angular motion.</api:text>
        </api:field>
        <!--other fields-->
      </api:native>
    </api:record>
  </api:records>
  <api:relationships href="https://localhost:8091/publications-api/publications/15/relationships"/>
</api:object>

Example data sources configured with a default installation of the Elements System are: arXiv, Cinii EN, Cinii JP, DBLP, manually-entered, figshare, PubMed, RePEc, SciVal Experts, Scopus, Web of Science and Web of Science Lite.

<api:record format="native" source-id="3" source-name="wos" source-display-name="Web of Science" id-at-source="A1986C172200006">...
...
<api:record format="native" source-id="2" source-name="pubmed" source-display-name="PubMed" id-at-source="3714102">...

From the above publication XML example's record/@source-name attributes we can see that the two records are from the Web of Science and PubMed respectively.

When consuming this publication, you have the choice to use either record, or a mixture of them both.

See the API schema documentation for more details about data sources.

All categories (except users) ship with two data sources configured: the manually-entered data source, which is always assigned a name of "manual" and the Institutional Source.

The manually-entered data sources (one for each category except users) typically represent data entered into the system manually by the users of the system at your institution (perhaps by file upload or by directly typing their details into the user interface). Often, an institution will also wish to import data from legacy systems into the Elements system flagged as manually-entered records.

The Institutional Source data source is a placeholder to represent your existing data system (if any). For example, you should use the identifier for this data source when importing data from your existing system into the Elements system. This way, the Elements system knows where the data came from.

Unless the data was directly transferred from an online data source such as arXiv, or a dedicated automated feed from systems at your institution, data uploaded into the system by users, or in a one-off manner in bulk by your institution, is usually considered manually-entered.

More information about the data sources currently configured at your institution is made available through the API itself. See the /data-sources resource.

From time to time the system will notice, or be told by an academic user or librarian, that two existing objects in the system refer to the same thing. For example, two publication objects might refer to the same published item in the real world.

The system may prompt interested users to merge the two objects in to one. This process is crucial to maintaining the accuracy of the data in the system.

Although it may not affect your particular use case as a consumer of the API, it may be helpful to have a brief overview of what happens during this process.

The newer of the objects is selected to be the "source", and the older object is selected to be the "destination" of the merge. All of the records of the source object are then transferred into the destination object, and the source object is deleted.

Any existing relationships of the source and destination objects to other objects in the system are managed during the merge process to most effectively preserve meaningful data. From the point of view of an API consumer, the "source" object will have been deleted; the "destination" object will have been modified; all relationships involving the "source" object will have been deleted; and the collection of relationships to the "destination" object may have been modified.

Occasionally, the reverse (a "split") will occur. A user of the system may notice that one record belonging to an object does not belong with the others, since it obviously refers to a different external entity than the others.

In this case, the offending record is removed from the object and placed inside a new object of its own. From the point of view of a consumer of the API, the original object will have been modified, and a new object will have been created.

For some sources, objects cannot contain more than one record, therefore it is not always possible to merge two objects that both contain a record from that data source.

For various reasons in the normal course of events, objects will be deleted from the system.

Because some external systems need to be able to know when an object has been deleted, information about the object will be accessible through the API in resources under the /deleted/{cats} part of the URI space, though the original resource representing the object will return a 410 (Gone) HTTP response.

Whenever a deleted object is requested from a URL under the /deleted/{cats} part of the URI space, the level of detail returned will be just enough to determine the identity of the object, plus a little extra administrative information. No nested elements will be provided, since the item has actually been deleted and the data is no longer available.

<api:deleted-object category="publication" id="10" deleted-when="2009-02-10T19:57:11+00:00" href="https://localhost:8091/publications-api/deleted/publications/10"/>

Each object has an ID given to it by the Element System. This is referred to simply as the object's ID and it is always an integer.

The value is persistent and unique only within the object's category, never changing or being reused by another object within the same category.

If the object is ever deleted, the API will still be able to tell you that the object has been deleted if you ask for the object of the same category with the same ID.

The category/ID pair is persistent and unique within the entire system and so the category/ID pair is the true unique identifier of the object.

<api:object category="publication" id="10"...

Users can also be assigned a Proprietary ID by your institution (an institution-wide staff-id or human-resources-id). For users with a Proprietary ID, it is a string value unique amongst all users that have ever been assigned one, but users are not required to have a Proprietary ID.

The Proprietary ID is passed to the Elements system by your institution when automatically feeding users in to the system using the API. By storing the Proprietary ID provided by your user feeds, the Elements System knows which users to update when their details change in the user feed you provide.

Each user is additionally assigned a username and authenticating authority pair, also given to him/her by your institution.

The username is unique amongst all active users that share the same authenticating authority and is used by the user to log in to the Elements system user interface (an active user is one who is not deleted and who is either a current member of staff or has not specifically been denied the ability to log in to the system). The authenticating authority lets the Elements system know which authentication system in your institution should perform the authentication during user login.

Think of the authentication authority as the name of the system in your institution in which the user’s login credentials are stored. The Elements system makes no guarantees to external systems that the usernames or authentication authority IDs of users will not be recycled or changed.

<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" is-deleted="false" href="https://localhost:8091/publications-api/users/5" created-when="2005-07-28T15:46:18.377+01:00" type-id="1">...

The main object ID is the identifying information natively used by the API for users (as for all other objects) and is the ID you should generally use to directly fetch the user’s data from the API. If you do not know the ID of a user, you can search for users by using the other two types of identifying user data (Proprietary ID or the authority/username combination), though you might return zero or multiple results, depending on your exact search settings and the distribution of usernames created by your institution.

The records belonging to a publication are often sourced from external data sources such as the Web of Science, PubMed, or arXiv. These records may have been assigned their own IDs by the external data sources.

Where such an ID exists and has been stored by the Elements system, the API will expose it in the details of the publication.

Do not confuse the external IDs of the records of a publication with the system ID of the publication itself.

<api:object category="publication" id="15" last-modified-when="2009-05-28T14:54:08.937+01:00"  href="https://localhost:8091/publications-api/publications/15" created-when="2006-07-05T00:20:20.833+01:00" type-id="5">
  <api:ever-approved>true</api:ever-approved>
  <api:records>
    <api:record format="native" source-id="3" source-name="wos" source-display-name="Web of Science" id-at-source="A1986C172200006">...

A relationship is a typed directed link from one object to another, which provides information about how the objects are related. No more than one relationship of each type may exist between any given pair of objects.

The relationship types provide the semantics of the Elements system's relational data storage.

An example relationship type is the "publication authorship" of a publication by a user. A relationship of this type is modelled in the system as a directed arrow of the appropriate type ID pointing from the publication to the user. This relationship indicates that the user is an author of the publication.

There are currently over 90 relationship types, each of which can be used to link an object of one specific category to an object of another specific category. For a comprehensive list of the relationship types, see the /relationship/types resource.

Some example relationships initially configured in the system are: publication derives from publication, publication authored by user, grant funds organisational structure, grant funds publication, equipment used by user, user is PhD student of user, and many others.

Apart from having a type, a relationship may hold other information such as the dates between which the relationship was or is active.

Each relationship is assigned a unique integer ID by the Elements system.

The Elements system makes relationships suggestions to users of the system. Such suggestions are then either accepted (the suggestion is removed and a fully fledged relationship is created) or declined (and are remembered as such and not reoffered). You can see the full list of pending and declined relationship suggestions using the /suggestions/relationships/pending and /suggestions/relationships/declined resources.

In the normal course of events, an unwanted relationship suggestion is declined rather than deleted. It is possible to delete a relationship suggestion instead of declining it, but to do so may risk the suggestion being made by the system a second time. Declining a relationship suggestion is the recommended way of dismissing it.

If your API account has write permissions, you have the ability to decline or accept any relationship suggestion in the system, as well as reoffer existing relationships or declined suggestions for acceptance. See the individual operations on relationships suggestions and relationships for more information.

<api:relationship-suggestion id="138" type-id="8" href="https://localhost:8091/publications-api/suggestions/relationships/138">
  <!--more data here if full detail was requested...-->

Symplectic Elements offers powerful research assessment functionality, and the API gives you access to the research assessment data stored in the Elements system. The “RA” resources cover the UK REF and the New Zealand PBRF research assessment exercises. The “HERDC” resources cover the Australian HERDC research assessment exercise (renamed to "Annual Collection" in Elements v5.4).

A HERDC return is particular to a year, and is the top level organisational entity representing all nominations for a particular return.

A HERDC nomination represents the nomination of a research output for inclusion in a HERDC return. Associated data includes information about which publication/record was originally nominated, plus workflow status, associated HERDC-specific organisational group structure, and various HERDC-specific authorship data.

An RA profile is the research assessment profile of a single Elements user, representing all of the information about the user relevant to your research assessment exercise, such as all of the user's nominated research outputs and declared special circumstances.

A research assessment output within the profile is created by the user when he/she nominates an existing research object in the system (such as a publication). At that point, the output is created from a snapshot of the data held in the object at the time of nomination, and thereafter enjoys an independent life within the user's research assessment profile. The output is represented by the API in a similar way to an object (although simplified).

If two users nominate the same publication (or other object), then two separate outputs are created in the two separate user research assessment profiles, and they remain independent of each other.

When implementing a client to consume the API, observe the following best practices:

Keep a note of which version of the Elements system's API you wrote your code to interact with. Not doing this may cause significant problems when you, or others, revisit your code.

Do not rely on the Elements system's logging alone. Some of your requests may not even reach Elements, for various reasons. Perhaps network issues are responsible, or the API has not been enabled. A bug in the API may prevent it from logging interactions, or the system administrator may have disabled certain levels of logging to ease the burden on the system.

Consider logging the following request information:

• Request URL and verb

• Exact time of request

• Size of content of request

Include an optional program parameter that will in addition cause your client to log the entire HTTP content of the requests it sends to Elements. You can switch this parameter on if you need to review the data you have been sending to the Elements system for debugging purposes, and switch it off again once you are done, to save disc space.

Consider logging the following response information:

• HTTP status code

• Any API error codes/messages returned in the body of the response

• The time taken from issuing the request to receiving the response

• All warnings returned by the API (look for an API warnings element in every ATOM entry element – see the section on Success Responses earlier in this document)

In addition, log any errors that occur in your own code.

If you are in control of the timing and frequency of requests to the API, then issue your API requests serially and build in a configurable wait time between the end of the processing of one request and the issuing of the next. Symplectic will ask you about how much sleep time you have built into your client code between requests when responding to Client Environment & Systems Support requests that enquire about performance issues.

If the Elements API is the bottleneck in the speed of data throughput, then you are overloading the Elements system and you should expect performance issues within Elements and for its users.

If you are not in control of the timing and frequency of requests to the API, then you have likely exposed the API indirectly to an uncontrolled and potentially high level of load, such as that which arrives in real-time from a directly connected website application. The API as a comprehensive data feed service is not designed to support such a role, and you should implement a caching solution to isolate the Elements system from frequent requests and unpredictable loads.

To remove unnecessary points of failure in your distributed architecture, and to isolate the Elements system from an uncontrolled and potentially high level of load caused by (often repeated) requests for the same data arriving to the API at a variable and unpredictable rate, always use a caching solution where possible.

Search for data in the Elements database through the API regularly and cache the data in a separate system in the form most efficiently served in your high/variable-load environment.

Symplectic will be happy to provide Client Environment & Systems Support in the form of advice or consultancy for implementations of such solutions as a part of your support agreement.

Not using a caching solution in a situation in which distributed load and/or risk to service availability would otherwise be significantly lowered is not a supported use of Elements.

When developing a client that supplies data to the API, make it a habit to explicitly check that any XML documents your client is submitting are both well-formed, and validate against the API schema using an XML validation tool. Such tools are available online free of charge. Some well-used tools for these purposes are https://validator.w3.org/ and https://www.xmlforasp.net/SchemaValidator.aspx, respectively.

Previously we have considered additions to existing enumerations in the API schema to be backwards breaking compatibility changes. For example, adding "teaching-activity" to the "api:category" type was considered to break compatibility, requiring a new endpoint. In the future we will no longer consider the addition of value to an enumeration as breaking compatibility. This will allow for quicker introduction of new functionality such as new relationship types and new categories.

Always use library code to generate your XML, and never generate it yourself using string-formatting and concatenation routines - this will always lead to trouble since, despite looking easy, XML is very hard to get right without using a proper XML library.

For example, beware that as per the XML standard, any Unicode characters not in the code point ranges 0x9, 0xA, 0xD, 0x20 - 0xD7FF, 0xE000 - 0xFFFD, 0x10000 - 0x10FFFF will render your XML invalid if present in the content of your XML, whether included literally or character-referenced. These characters can easily appear in your documents if you have copied and pasted text from (for example) Microsoft Word, or if you embed data from a database of yours straight into an XML document as pure text.

All modern programming languages make available at least one good XML library.

Review the implementation of your client once a year, and bring its compatibility level up to date with the latest version of the API that you are running at your institution.

You might not have been aware that your institution has upgraded its Elements system, and that your client is still using an old compatibility endpoint that will one day stop being supported, so scheduling a regular review of your client is a good idea. Contact your system administrator and ask which version of the system is running, compare this with the version you wrote your client to work with, and schedule time to upgrade your client.

This way, you will not be faced with having to suddenly update an old client written against a very old API compatibility level, for which your newest version of Elements no longer provides a backwards compatible endpoint.

In each release of the system, Symplectic provides API endpoints for compatibility levels for several earlier versions of the product. This gives you a reasonably long period in which to upgrade your system connections. But don't be caught out.

This response is made by the operating system when you access a secure HTTPS endpoint to which your IT support/application administrator has not assigned an SSL certificate.

Contact your administrator and request that your IT staff binds an SSL certificate to the port to which you are trying to connect. Instructions for this process are supplied in the 'API Administrator Guide'.

1. Check the response for ATOM content. If ATOM content is returned, see the contained API error code and human-readable explanation of the error.

2. Check that the URL of the operation you are attempting is correctly formed. For example, the URL must not contain a double-slash except immediately after the scheme (http://).

3. If you are using a PUT or POST based operation, check that your request includes a "Content-Type: text/xml" HTTP header.

4. Check that any XML that you are providing is well-formed. You can use online tools to help you with this, for example https://validator.w3.org/. Always use library code to generate your XML, as discussed in Best Practices.

5. Check that any XML that you are providing is validated by the API schema. You can use online tools to help you with this, for example https://www.xmlforasp.net/SchemaValidator.aspx. This is the most common way to cause a Bad Request response. Sometimes, an online validator like this will suggest that the problem is deeply nested in your XML when the actual problem is a missing or incorrect namespace on your document (root) element.

6. If the operation you are attempting offers a "validate" parameter, repeat the request setting this value to "true", and read any resulting error message. Do not use this parameter as a matter of course in live production code, as it causes a significant performance hit on the Elements system and is only provided to temporarily help you with your debugging.

You have not correctly (or at all) submitted your credentials with your request, or your credentials were invalid.

Make sure that you are supplying a "WWW-Authenticate" header with every request. The value of the header should be the string "Basic " (including the trailing space character) concatenated with the base 64 encoded value of the UTF-8 encoded value of the string "username:password" (replace "username" with your username, and "password" with your password).

For example, the username "foo" with the password "bar" should be submitted using the following HTTP header:

WWW-Authenticate: Basic Zm9vOmJhcg==

The steps to achieve this are

1. "username:password" becomes "foo:bar"

2. "foo:bar" encoded using UTF-8 becomes the byte array [0x66, 0x6f, 0x6f, 0x3a, 0x62, 0x61, 0x72].

3. The byte array [0x66, 0x6f, 0x6f, 0x3a, 0x62, 0x61, 0x72] represented in base 64 is the string "Zm9vOmJhcg==".

If you are correctly attaching your credentials and still seeing this response, then either your credentials are invalid or you are accessing the API from a machine whose IP address has not been registered with the Elements system. Contact your system administrator, providing him or her with your machine’s IP address.

Check with the system administrator that the account corresponding to the credentials you are using has the required permissions for the operation you are attempting. If you are attempting an operation with anything except the "GET" HTTP method, your account requires read/write access to the Elements database. See the GET /my-account operation to review the rights that your account has been assigned.

Standard HTTP endpoints from v4.9 compatibility level onwards 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.

1. Use a telnet client from the machine on which your client is running to verify that the target port is open on the target machine. If it is, then the API is available for connections. Contact your network support for more help.

2. Check with your system administrator that the API has been configured by your institution to run on the port you are attempting to access.

3. Check with your system administrator that the API has been switched on.

4. Contact your system administrator to have them check using a telnet client on the machine on which the API is running to verify that the target port is open when accessed from that machine. If so, the problem is a firewall or network configuration problem. Contact your local network support for assistance.

1. Log the full details of the requests that are causing the timeout to understand the timing of the requests you are making and the amount of time the requests are taking to respond.

2. Are you executing multiple concurrent requests to a plan? If so, scale back the concurrency and introduce sleep time between receiving responses and issuing new requests.

3. Are you executing requests at a varying rate determined by an external stimulus such as incoming requests from the internet? Do the timeouts occur at periods of high demand? If so, the number of requests per second is reaching too high a value for the Elements system, and you need to reengineer your solution to use a caching approach. See the Best Practices section of the Appendix.

4. Can you verify that the timeouts consistently occur for some supplied parameters, but not for others, when requesting the same operation? If so, contact the Symplectic support desk.

5. Are you executing your requests at the same time as a scheduled system process? If you find your performance problems occur at regular intervals, this is likely the case. Liaise with the system administrator to find an alternative time to run your requests against the API.

6. Are you building in any sleep time between receiving a response and the issuing of the next request? Increase this wait time and monitor any change in the incidence of timeouts.