Developer’s guide

MegaMatcher ABIS can be programmed using RESTful API. There are two main categories of available APIs:

• Biometric API includes functionality for registering transactions, checking transaction statuses, getting transaction results, etc. Also, functionality related with adjudication workflows is included. It is usually used for integrating MegaMatcher ABIS with customers applications or external systems.
• Administration API is used to automate various administrative tasks and also to analyze and supervise all the things that happen in the MegaMatcher ABIS.

Biometric operations in MegaMatcher ABIS are represented as transactions (enroll with duplicate check, delete, verify, identify, etc.). Some transactions may be processed immediately, some may take long time to complete. For example, enroll with duplicate check transaction may required human operator to take the final decision in some cases.

Therefore, transaction API is asynchronous. First, transaction is registered in the MegaMatcher ABIS system. Note that registration operation result does not indicate whether transaction has completed successfully. Register request returns a unique transaction ID which can be used to track the transaction further.

In order to determine the outcome of biometric transactions, transaction status needs to be checked by polling MegaMatcher ABIS  periodically. Also, custom extension is possible which may notify other system when transaction is complete.

When communication with MegaMatcher ABIS, client application may experience transient errors. These kind of errors indicate that the system temporarily cannot perform operation (such as network temporary unavailable, MegaMatcher ABIS unit on server side is not functioning and backup unit is taking over, etc.). But when retrying an operation after some delay, it will most often complete successfully. In order not to overload the MegaMatcher ABIS when a lot of operations are retried at the same time, it is recommended to increase the interval between retries after each attempt.

There is some group of errors which can be considered transient (where retries should be attempted), while the others indicate some permanent failure such as wrong input data. Transient errors include HTTP error codes 502, 503, 504, and any timeout exceptions which depend on programming language used. Please refer to sample applications which demonstrate how to perform query with retries in case
of transient errors.

When repeating transaction registration request, there is a risk that the previous request has succeeded but a response could not be returned because of a failure. In order to avoid possibility of repeating the same transaction when retrying failed operations, a user specified transactionId may be provided to register transaction request. When MegaMatcher ABIS receives request with a transactionId that is has seen before, it will return the id of the previous transaction registration and will not perform a registration again. Client application is required to ensure that transactionId is globally unique (Guid or UUID may be useful for this).

MegaMatcher ABIS API package provides ready to use libraries and code samples for .NET and Java. Other language client libraries can be generated from provided Swagger specifications.

.NET client libraries can be found in Bin/dotNET directory. Neurotec.Abis.Client.Management.Rest.dll library provides Biometric API (and also contains authentication helper methods which may be useful when using administration library). Neurotec.Abis.Client.Administration.Rest.dll library provides Administration API. The necessary libraries should be added as References to .NET project. Samples for .NET are provided in C# and can be found in Samples/{CatagoryName}/CS.

Java client libraries can be found in Bin/Java directory. com-neurotec-abis-client-management-rest.jar library provides Biometric API. com-neurotec-abis-client-administration-rest.jar library provides Administration API.

MegaMatcher ABIS APIs are specified using Swagger (see http://swagger.io/) which allows to generate client libraries for most popular programming languages. Swagger provides all the necessary tools, for example Swagger Online Editor makes it extremely easy to load Swagger specification and generate client library for chosen library using simple user interface: http://editor.swagger.io/#/ .

Authentication for MegaMatcher ABIS uses OAuth2. There are many libraries available which make using of it easy. Some examples of libraries are covered in this section, but other OAuth2 libraries could be used instead.

Use the following method to initialize a particular MegaMatcher ABIS API service class and conduct authentication:
ApiFactory.createApi(serviceClass, serverIp, “admin”, “admin”);
Please note that serverIp has to be set to actual IP address of the server. In example, default credentials “admin”/”admin” are used, which should be changed in production system.

The following code snippet demonstrates how to get an authentication token (auth.AccessToken) and how to create an API instance:

string BasePath = "http://172.16.0.185"; // TODO: change to http:// + MMABIS server address.
string ServicePath = "/mmabis/rs/client/v1";
var auth = await ApiAuthentication.AuthenticateAsync(baseUrl, Username, Password);
var apiInstance = new TransactionsApi(BasePath + ServicePath);
apiInstance.Configuration.AccessToken = auth.AccessToken;

Please note that the simple authentication provided in .NET client library does not refresh tokens automatically. It is needed to refresh them manually when approaching expiration time:

await auth.RefreshTokenAsync().ConfigureAwait(false);
apiInstance.Configuration.AccessToken = auth.AccessToken;

For most programming languages there are ready to use OAuth2 libraries available which should be used for authentication. This section demonstrates how to perform the steps manually using HTTP requests. This can be also useful to see what parameters need to be passed to appropriate libraries.

Please note that OAuth2 supports a lot of variations how to obtain and refresh tokens (such as using GET or POST methods, passing clientId through Authorization header, etc.). Many of them are supported by MegaMatcher ABIS, but this section only demonstrates the most simple ones.

GET http://<yourIp>/oauth/token?
grant_type=password&client_id=mmabis&username=<yourUsername>&password=<yourPassword>

<yourIp>, <yourUsername>, <yourPassword> need to be replaced with actual values.
In case request completes successfully, a small Json object is returned which contains the following
fields:

• access_token
• refresh_token
• expires_in – duration in seconds when the access token will expire.

GET http://<yourIp>/oauth/token?
grant_type=refresh_token&client_id=mmabis&refresh_token=<yourRefreshToken>

<yourIp>, <yourRefreshToken> need to be replaced with actual values.

The response is the same Json object as in case of obtaining access token for the first time.

Each HTTP request to MegaMatcher ABIS needs to be authenticated by adding “Authentication” header which contains value “Bearer <yourAccessToken>”. <yourAccessToken> should be replaced with the actual access token value.

MegaMatcher ABIS developer API package includes some samples which demonstrate typical use cases and some best practices.

Batch enroll sample demonstrates how to enroll with duplicate check a large number of ANSI/NIST templates found in specified directory. It is available in C# and Java.

The sample performs multiple transactions in parallel for efficiency. It demonstrates how to perform operations with retries in case of transient errors. Also unique transactionId is specified so that the same transactions will not be registered multiple times.

Note that the sample waits for transaction to either complete or go into adjudication. It does not wait for adjudication to complete (which may be necessary for other use-cases).

Biometric client demonstrates how to perform basic operations using MegaMatcher ABIS: enroll, identify, verify, delete, update, verify-update. It is available in C# and Java.

Note that for simplicity and in order not to overload the sample with details, it is missing some details which may not be needed for prototype but are usually used in production: operation retries in case of failures, etc. Please refer to more complex Batch enroll sample for details.

Complete MegaMatcher ABIS RESTful API reference is provided in the API package:
• Biometric API
• Administration API

If you need additional information how to use the MegaMatcher ABIS RESTful API or have other questions related with MegaMatcher technology, don’t hesitate to contact Neurotechnology support team who will be happy to help: support@neurotechnology.com