LUIS API

History

The Livestock Unique Identifier System (LUIS) has been developed to replace the current ageing legacy systems for animal identification systems for cattle, sheep and goats (CETAS and S&GETAS). LUIS will be a single GB-wide service for all species.

The LUIS system will deliver the many improvements including:

• A browser-based user interface
• Faster number allocation
• Faster response times with the ability to identify invalid tags, CPH or other issues in real time.
• Online control - LUIS enables self-serve which previously required assistance, including Cancelling tags and recovering tags, including those cancelled in error.
• Identifying problems with out-of-sync number ranges, such as when a keeper orders primary and secondary tags from different Ear Tag Manufacturers (ETM’s).
• Online declaration documents that mean ETMs can process their own cancellations
• A set of Restful APIs to allow ETMs to integrate their own systems with LUIS

For more details about the Hello World API, open an API browser like Swagger Editor and copy the Open API file content into it.

You can also generate a client library from the Open API file using Swagger Editor.

Purpose

The purpose of the document is to provide Ear Tag Manufacturers (ETM’s) and their development teams the necessary information to integrate their systems into LUIS, using the APIs. This document specifies the interfaces and their expected behaviours, listing the errors or warning conditions that may occur should they fail.

Technical Knowledge Requirements and Limitations

The document assumes that the reader has the necessary technical knowledge required to write the software required to use these APIs. It should be read in conjunction with the online Swagger documentation. It is a developer’s guide to the service and its functions.  It does not provide details on how to implement this within a ETMs application, as each one will be unique and is the responsibility of the ETMs. It describes and specifies the API service interfaces that will be exposed for Ear Tag Manufacturers (ETM’s) to integrate their systems with the LUIS application. These APIs are used within the LUIS User Interface (UI). ETMS can use the UI to validate results and see how the APIs perform. The APIs are an optional method of interacting with LUIS and a web application is available for those who choose not to do so.

Document Versions

While every effort will be made to keep this document up to date, it should be remembered that LUIS is still under development and will therefore change. Swagger will have the most up to date APIs definitions.

API Suite

There are a wide range of APIs for ETMs to use and not all will be applicable to everyone. Each ETM has the option and flexibility to integrate with as many or as few of these APIs as they choose. There is no one size fits all. The information returned may be too detailed for some ETMs who may choose to only use part of the information returned in the Json.

A Net Standard 2.0 class library (LuisApi.dll) is available to enable developers to strongly type order inputs and specific response formats. This is available at https://www.nuget.org/packages/luisapi

Important Changes to Business Processes

Developers should be aware that several of the business process that surround tag ordering have been changed:

Mandatory Fields

More mandatory information is required about the tag order than in the old systems. This includes Tag Colour and red replacement tags that are now ordered seperately.

Tag Ids and Colours

Tag Ids and colours can be obtained using the Manufacturer’s Approved Tags API (6.3). The tag colours are case sensitive.

Unmatched Tags

There is now the concept of unmatched tags. This occurs when a pair of tags is ordered from 2 separate ETMs. If the primary is ordered first, until the secondary tag is ordered no more primary tags can be ordered. Unmatched tags only relate to a single species and herd/flock. i.e. if a keeper has cattle and sheep , unmatched cattle tags would not prevent an order being placed for sheep tags.

Tattoos

If a keeper orders an EID sheep tag and applies a tattoo as the second identifier, LUIS must record the tattoo to balance the order. A Tattoo has been created as a common generic tag across all manufacturers and must be selected to remove the unmatched tags.

Important Changes to Data

LUIS will issue new unique references for the following:

• Manufacturer Id
• New tag reference numbers for all tags. This is known as 'Approved_Tag_Id' and is used on all orders placed using the APIs

It is hoped that the manufacturer id and the Approved_Tag_Id issued on the test system will be the same as the live system. Manufacturers will need to double check this before moving into production

Auditing and System Use

All use of the APIs within LUIS is recorded and a full audit history is kept. Any misuse or attempted misuse of the APIs may result in them being withdrawn from that ETM.

Data Protection

ETMs can only see the full details of their own tags and orders. While it is possible sometimes to see some information about an order when ordering replica tags, the information returned has been redacted to hide the other ETM or tags previously ordered. The APIs below are returning the full data set and are based on the order being solely for that manufacturer.

Help and Support

LI Ltd will endeavour to help and support ETMs and their developers while they integrate these APIs with their systems but have no responsibility for ensuring the APIs work within the ETMs application. If you encounter any issues, please contact nick.morris@livestockinformation.org.uk

In scope

For release 1 of LUIS (Sheep and Goats), the APIs that will be available to ETMs are:

• Keeper validation
• Ordering of new tags
• Ordering replica tags

Out of scope

Out of scope for this release:

• Order cancellations
• Order recoveries

For this initial testing phase, it will be possible to use the APIs to order cattle tags. This is to allow ETMs to provide feedback and to allow them to embed the functionality into their systems. To that end, the APIs will also allow for testing of cattle EID orders. This again is to allow early testing of this functionality and give ETMs the opportunity to provide feedback.

During this development phase, we expect to make some improvements to the APIs in response to feedback from ETMS. These changes will be advised to ETMs and made available as quickly as possible.

To use the APIs an ETM requires:

1. A service account - the LUIS admin team, who will issue a User Id and a password, creates this. This information will be sent in 2 separate emails
2. Provide LI ltd the ip address(es) and or the ip range(s) that will be access the APIs

Section 6.1 below describes the process for obtaining a token. The token issued by the LUIS application is valid for 30 minutes. However, to prevent a time out mid order, it is recommended that a new token is requested for each API call.

This bearer token must be included in the security header of the Json to authenticate each call. The format is Bearer(space)Token

Only calls originating from the registered IP addresses will be accepted by the application.

No help message is given at this stage as to the user, if this call fails for obvious security reasons.

The password for the API will be changed from time to time. The frequency of this change is yet to be determined but ETMs will be advised in advance of any change.