API Administrator Guide

This document provides administrator documentation for the latest Elements API version (v6.13) and provides your administrative and IT staff with the ability to troubleshoot the running and alter the configuration of the API.

This guide is designed to be read in conjunction with:

• Manage the Elements API

• API User Guide

• v6.13 Postman collection

• Changes from v5.5 to v6.13

• Schema Definition

• v6.13 Requests and Responses

The API works in a similar way to an interactive webpage, to which publications information is supplied after queries are sent to the system. However, instead of being supplied in HTML code and read by a person through a web browser, the information is supplied in XML code and read by other machines. The operation of the API is largely controlled by the administrators of these other systems, who will set them up to submit queries and read the results. The API is implemented as a single scheduled process hosting a number of configurable endpoints at addresses defined by you.

By default, only secure endpoints are enabled at the point of installation of Elements. If you wish to enable legacy endpoints to allow legacy code to continue to work with the Elements API, or to allow unsecured access to API versions 5.5 and above, you must configure the API to enable additional endpoints.

All unsecured endpoints do not authenticate the client, and grant full authorisation to all clients on all data. If you wish to restrict access to data, you must disable all unsecured endpoints.

For hosted clients, please raise a ticket, and Symplectic will configure and create an end for you.

Every time you reconfigure your endpoints, you must contact your IT staff to have them:

1. reconfigure the operating system to grant the API process the right to listen on the configured URL.

2. bind a valid SSL certificate to the appropriate port if the endpoint is a secure endpoint.

In order to do the above tasks, your IT team must observe the following instructions on the server on which the API is running:

1. ACL configuration

   • Review with you which URLs (including the ports) are required by the API.

   • Review which Windows Principal is running the API. This will be the same Windows Principal that is running the Elements Scheduler Windows Service.

   • Use the command below to review which Windows Principals are registered against which URLs:

     netsh http show urlacl

   • Use the command netsh http add urlacl with additional parameters to register any missing URLs against the Windows Principal running the API. See https://msdn.microsoft.com/en-us/library/ms733768.aspxfor more details. For example:

     netsh http add urlacl url=https://+:8091/ user=HOSTNAME\Username

2. SSL certificate configuration

   • Review with you which secure (HTTPS) URLs (including the ports) are required by the API.

   • Execute the command below to view the current port SSL configuration to see which ports used by secure endpoints are not configured with SSL certificates.

     netsh http show sslcert

   • Install a suitable SSL certificate if none are installed on the local machine.

   • Get the thumbprint of a suitable installed SSL certificate.

   • Use the API port and the certificate thumbprint as replacements for the bold values in the command.

     netsh http add sslcert ipport=0.0.0.0:8091 certhash=13ff526b6bdee4a01608700db15848f5a47aa500 appid={00112233-4455-6677-8899-AABBCCDDEEFF}

For more details, see https://msdn.microsoft.com/en-us/library/ms733791.aspx

All clients accessing the API must have an IP address that you have registered with the Elements system. Once you have registered an IP address, you must restart the API for the changes to take effect. To restart the API, use the System Admin > Jobs & Scheduling> Scheduled Jobs page of the Elements user interface. If Symplectic hosts Elements for your insitution, you'll also need to request that the IP is added to the allow list in the firewall system.

A client accessing the API from an unregistered IP address will receive an HTTP 401 response (or 403 on some legacy endpoints) and an error message from the API indicating unauthorised access, and will likely contact you to register their IP address.

To confirm absolutely whether or not it is in fact the IP address of the client that is being rejected, inspect the "warnings" text logs of the API, found in the "Api.Host/logs" directory within the Elements installation directory. All requests that fail due to unregistered IP addresses are logged here.

In order to access a secure v4.9 endpoint, you must configure an API account on the API accounts page, and let the programmer implementing against the endpoint know the credentials you have assigned to the account. See the Manage the Elements API documentation to configure these screens.

A client accessing the API using invalid credentials will receive an HTTP 401 response and an error message from the API indicating unauthorised access, and will likely contact you for help.

To confirm absolutely whether or not it is in fact the credentials of the client that are being rejected, inspect the 'warnings' text logs of the API, found in <Main_Installation_Folder>/Api.Host/logs/. All requests that fail due to invalid credentials are logged here.

Note: these API Host logs are separate to the system log that can be viewed in the user interface at System Admin > Logs and Monitoring System log. They can only be viewed in the text files in <Main_Installation_Folder>/API.Host/logs.

Note: Remember that <Main_Installation_Folder> refers to the folder on your server where the Elements binaries are installed e.g. "C:/Symplectic/Elements".

For Self-Hosted clients, the API can be configured by you to offer different endpoints, each of which is served at a different URL and offers clients a different level of backwards compatibility or functionality.

For hosted clients, please raise a ticket, and Symplectic will create an endpoint for you.  

The types of endpoint are:

It is up to you which levels of backwards compatible endpoints you wish to enable or disable. The fewer backwards compatible endpoints you configure, the more pressure your institution will be under to keep its API clients up-to-date with the latest endpoint functionality. As Elements develops, the oldest compatibility levels will be removed.

For endpoints that serve functionality from previous version of Elements, your programmers must use the documentation that came with that version of Elements.

The Standard endpoint types are the API endpoint types against which your programmers should implement their data feeds, and you should always encourage your IT staff to implement against the very latest compatibility mode. Use System Admin > Manange API > API Endpoints to configure the endpoints; this is outlined in the Manage the Elements API documentation.

Users of the API are asked to liaise with the System Administrators in order to agree their planned use of the service.

When agreeing the timing of their requests, you should aim to avoid placing undue stress on the system during office hours, when the system will need to be responsive to ordinary users.

You will also want to avoid clashes with administrative processes the system itself carries out, such as processing user information (see below).

The user information stored by Elements will usually be fed into the system by your institution’s HR system. This will occur on a regular schedule.

You should liaise with the administrators of the system that provides the user feed to arrange a suitable time for the user feed table to be repopulated.

The process works in two stages:

1. The Elements API is used to populate a holding table stored within Elements.

2. The system processes the holding table and makes the appropriate changes to the user information within the system.

Therefore, while the HR system can populate the user table effectively at any time, you should be careful to choose a suitable time after this to schedule the processing of the feed. If any changes are needed as a result of changes to the use of the Elements API, you can do this from System Admin > Operations > Scheduled Jobs.

Each API account can be assigned any of the following rights:

Can access HR data

This setting determines whether the account can access "restricted HR data", which is defined as the set of User Generic Fields 11-50, and whether the account can access HR feed (user account creation etc.) functionality in the API. Please see the following articles for more information:

• User Generic Fields and Restricted HR Data

Any data stored in these fields by your institution will not be visible to API accounts that do not have this right or to users of the Elements web application without suitably privileged administrator access. In addition, without this right, the API account cannot implement an HR data feed into the system.

Can access RA data

API accounts without this right cannot access data held within any of the Research Assessment portfolios in Elements. Currently, RA data means only data available through a HERDC exercise. Data from the Assessment module is not available via the API.

Can modify data

You should grant this right to accounts that are to be used to import HR feeds or other data in to the Elements system. Withholding this right prevents the account from altering any research data in Elements.

Warning: If you choose to expose an unsecured endpoint, you will not be able to restrict API access to authenticated users; nor will you be able to assign different rights to different users. All users accessing an unsecured endpoint will automatically be logged into an anonymous account and will be treated as though they have full API rights.

This section provides you with a few common scenarios in which you are approached by a programmer who is struggling to work with the API.

Occasionally, users of the API may report that they are experiencing errors. You can investigate these errors via System Admin > Operations > System Log. To see only logs from the Elements API, in the 'Filter results' box, find the 'System component' drop-down menu and choose 'API webservice'.

Check both the System Log (System Admin > Operations > System Log) and the API server logs (<Main_Installation_Folder>\Api.Host\Logs) for error messages. If you check the log files and see the following errors then you may have enabled two API endpoints against the same port (8443 in this example).

Message: Failed to listen on prefix 'http://+:8443/elements-api/' because it conflicts with an existing registration on the machine.
Message: HTTP could not register URL http://+:8443/elements-api/. Another application has already registered this URL with HTTP.SYS.

You can read about logs in more detail in the System Log support article.