mHUB - API Reference

 

General

The following format of response is returned by all requests.

Success Response

Name Value Description
status “OK” Indicates success

Error Response

Name Value Description
status “FAIL” Indicates an error occurred
errorMsgs <error messages> List of error message in an array

 

 

Engines collection

Resources relative to http://host:8080/matchITHub

Before you can start adding data to the matchIT Hub Service you must create an instance of a Hub Engine.

REST resource Summary
GET engines get a list of instantiated engines
POST engines create engine/session and initialize.
Form data: activation_code=<code>
DELETE engines/<engine id> delete engine/session

 

 

GET /matchITHub/engines

Response

Name Value Description
ids <engine>,<engine>,... Comma separated list of the ids of all current engine instances

Description

Returns a list of active engine numbers.

E.g.

GETengines.png
 
 

POST /matchITHub/engines

Request

Type Name Description
FormParam activation_code The hub activation code
FormParam name A name to give the engine instance

Response

Name Value Description
Engine <engine> The id of a newly created engine instance

Description

Initialises an instance of the engine and applies the activation_code.

The activation_code can be omitted, in which case a valid activation code must be PUT to the Initialization resource before the engine instance can be used.

If you supply a name for an instance, you can use this as <engine> in the url instead of the instance number.

 

DELETE /matchITHub/engines/<engine>

Request

engine
Type Name Description
PathParam engine The id number (or name) of the engine instance to delete

Description

Deletes the specified engine instance.

 

Logging

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
POST log Set the filename and severity level for logging
Form data: filename=<filename>, severity=<severity>

 

POST /matchITHub/engines/<engine>/log filename=<filename>, severity=<severity>

Request

Type Name Description
PathParam engine The id of the engine to modify
FormParam filename Name a file to write log messages to
FormParam severity The severity level of messages to log

Description

Configures logging which is disabled by default.

Severity is one of :

  • None
  • Error
  • Warning
  • Information
  • Debug

Setting severity to "Error" will log only error messages, setting severity to "Warning" will log error and warning messages, and so on. I.e. each setting is more verbose than the previous with "Debug" being the most verbose.

If filename is not specified (or is not accessible) messages are logged to the console (not visible when run as a Windows service).

Note: logging settings are per engine instance, but you can set all instances to log messages to the same file.

Log messages are of the form:

<engine id>,<HH:mm:ss>,<severity>,<source>,<message>

 

Initialization

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
PUT initialization?activation_code=<code> Apply an activation code to an uninitialized engine instance

PUT /matchITHub/engines/<engine>/initialization?activation_code=<activation_code>

Request

Type Name Description
PathParam engine The id of the engine to modify
QueryParam activation_code The hub activation code

Description

Initialises an instance of the engine and applies the activation_code.

 

State

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
GET state Gets the state of the engine
PUT ?state="pause" Pause a running engine
PUT ?state="resume" Resume a paused engine
PUT ?state="abort" Abort
PUT ?state="reset" Reset

 

GET /matchITHub/engines/<engine>/state

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value
State “uninitialized”, “initialized”, “ready”, “running”, “paused”, “finished”, “aborted”

Description

Gets the state of the engine.

E.g.

 

PUT /matchITHub/engines/<engine>?state=<state>

Request

Type Name Description
PathParam engine The id of the engine to modify
QueryParam state The state to change the engine to: “pause”, “resume”, “abort”, “reset”

Description

Changes the state of the engine. Equivalent to the hub methods: pause, resume, abort, reset.

  

Settings

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
POST settings Apply settings supplied in an xml string.
Form data: xml=<xml>
POST settings Apply settings supplied in a stream.
Form data: file=<file>
GET settings Retrieve the engine’s current settings
GET settings/advanced Retrieve the engine’s current advanced settings

 

POST /matchITHub/engines/<engine>/settings xml=<xml>

Request

Type Name Description
PathParam engine The id of the engine to modify
FormParam xml Xml settings string

Description

Applies the given settings.

 

POST /matchITHub/engines/<engine>/settings file=<file>

Request

Type Name Description
PathParam engine The id of the engine to modify
FormDataParam file Xml settings file

Description

Uploads a file of settings to apply.

 

GET /matchITHub/engines/<engine>/settings

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
configXML <xml string> Xml settings string

Description

Retrieves and returns the engine's current settings as an XML-formatted string.

E.g.

 

GET /matchITHub/engines/<engine>/settings/advanced

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
configXML <xml string> Xml settings string

Description

Retrieves and returns the engine's current advanced settings as an XML-formatted string.

 
 

Data

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
POST tables/<0,1,2> Add a single data record to a table.
Form data: data=<data>
timeout=<timeout>
POST tables/<0,1,2> Add a block of data to a table.
<data_block>
POST tables/<0,1,2>/files Specify a filename for the service to load input data from.
Form data:filename=<filename>
delimiter=<delim>
nomore="true"/"false"
encoding=<encoding>
timeout=<timeout>
POST tables/<0,1,2>/update Update a data record, the unique ref of the record to update is extracted from data
Form data:data=<data>
timeout=<timeout>
POST tables/<0,1,2>/update Upload a block of transactions to a table
<data_block>
POST tables/<0,1,2>/update/files Specify a filename for the service to load transactions from
Form data: filename=<filename>
delimiter=<delim>
nomore="true"/"false"
encoding=<encoding>
timeout=<timeout>
PUT tables/<0,1,2>/eof Inform the engine that no more data will be added
DELETE tables/<0,1,2>/eof Inform the engine to allow more data to be added
GET unprocessed Returns the number of unprocessed records
GET tables/<0,1,2>/<unique_ref> Get a record from a table by it’s uniqueId
DELETE tables/<0,1,2>/<unique_ref> Delete a record from a table by it’s uniqueId
DELETE tables/<0,1,2> Clear the data in a table

 

POST /matchITHub/engines/<engine>/tables/<table> data=<data>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
FormParam data A data record to add
FormParam timeout Timeout in milliseconds (default 1000)

Description

Adds data to the engine's input buffer.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

POST /matchITHub/engines/<engine>/tables/<table> <data_block>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
text/plain n/a Block of data records

Description

Uploads a block of data records to add to the engine's input buffer.

The content of this POST is a plain text block of records. Records should be separated by a new line characters and each record must start with the delimiter character used for that record.

POST /matchITHub/engines/<engine>/tables/<table>/files filename=<filename>, delimiter=<delim>, nomore="true/false", encoding=<encoding>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
FormParam filename Name of input file to load data from
FormParam delimiter The field delimiter used in the file
FormParam nomore "true" if no more data will be added to this table
FormParam encoding The encoding used in the file: "UTF-8" (default), "ISO-8859-1", "US-ASCII", "UTF-16", "UTF-16BE", "UTF-16LE"
FormParam timeout Timeout in milliseconds (default 1000)

Description

Specify a filename for the service to load input data from.. Filenames are added to a list and processed in the order added. If no delimiter is specified, each record must start with the delimiter character used for that record. If no encoding is specified, UTF-8 is used.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

POST /matchITHub/engines/<engine>/tables/<table>/update data=<data>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
FormParam data A data record to update
FormParam timeout Timeout in milliseconds (default 1000)

Description

Update a record with the new data. The unique ID of the record to update is extracted from the data.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

POST /matchITHub/engines/<engine>/tables/<table>/update <block_data>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0 or 1)
text/plain n/a Block of transaction records

Description

Uploads a block of transaction records to add to the engine's input buffer.

The content of this POST is a plain text block of records. Records should be separated by a new line characters and each record must start with the delimiter character used for that record.

Transactions

The first field in a transaction is the transaction type. Transaction types are:

  • A(dd)
  • U(pdate)
  • D(elete)

The rest of the fields depend on the transaction type. I.e.:

  • |A|record
  • |U|record
  • |D|unique_ref
    or
  • |D|record

Where <record> is the record (matching the table layout) to add or update and <unique_ref> identifies the record to delete. A delete transaction can either contain just the unique_ref of the record to delete or can contain a record matching the table layout that contains the unique_ref - all other fields are ignored and can be empty.

 

POST /matchITHub/engines/<engine>/tables/<table>/update/files filename=<filename>, delimiter=<delim>, nomore="true/false", encoding=<encoding>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
FormParam filename Name of input file to load data from
FormParam delimiter The field delimiter used in the file
FormParam nomore "true" if no more data will be added to this table
FormParam encoding The encoding used in the file: "UTF-8" (default), "ISO-8859-1", "US-ASCII", "UTF-16", "UTF-16BE", "UTF-16LE"
FormParam timeout Timeout in milliseconds (default 1000)

Description

Specify a filename for the service to load update transaction data from. Filenames are added to the same list used for input data and processed in the order added. If no delimiter is specified, each record must start with the delimiter character used for that record. If no encoding is specified, UTF-8 is used.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

PUT /matchITHub/engines/<engine>/tables/<table>/eof

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)

Description

Informs the engine that no more data will be added for the indicated table.

 

DELETE /matchITHub/engines/<engine>/tables/<table>/eof

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)

Description

Informs the engine to allow more data to be added for the indicated table.

 

GET /matchITHub/engines/<engine>/unprocessed

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
unprocesseCount <count> Count of unprocessed records

Description

Returns the number of records that have not yet been processed.

E.g.

 
 

GET /matchITHub/engines/<engine>/tables/<table>/<unique_ref>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
PathParam engine The unique ID of the record to fetch

Response

Name Value Description
result <data record> The record requested

Description

Get a record with the specified unique ID.

E.g.

DELETE /matchITHub/engines/<engine>/tables/<table>/<unique_ref>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)
PathParam engine The unique ID of the record to delete

Description

Delete a record with the specified unique ID.

 

DELETE /matchITHub/engines/<engine>/tables/<table>

Request

Type Name Description
PathParam engine The id of the engine to modify
PathParam table The number of the table to modify (0, 1, or 2)

Description

Removes and discards all data relating to the indicated table. This includes: buffered input data, cached records, clusters, matching pairs, matching groups.

 

Results

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
GET results/count Returns the number of buffered results
POST results/next Returns the next buffered result
Form data: timeout=<timeout>
POST results Download a block of results as plain text
Form data: timeout=<timeout>
POST results/outputfile Specify a filename for the service to write results to
Form data:filename=<filename>
encoding=<encoding>
timeout=<timeout>
DELETE results Clear the results

 

GET /matchITHub/engines/<engine>/results/count

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
resultCount <count> Count of results

Description

Returns the number of buffered results in the output buffer.

 

POST /matchITHub/engines/<engine>/results/next timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to query
FormParam timeout Timeout in milliseconds (default 1000)

Response

Name Value Description
result <record> Result record

Description

Gets and returns the next buffered result and removes it from the output buffer.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

POST /matchITHub/engines/<engine>/results timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to query
FormParam timeout Timeout in milliseconds (default 1000)
FormParam limit The maximum number of records to return in one go

Response

Unlike other methods, this method does not return a application/json format response. Instead the response is a text/plain stream of records delimited by newline

Description

Gets and returns all the results as a plain text stream.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

POST /matchITHub/engines/<engine>/results/outputfile filename=<filename>, encoding=<encoding>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to query
FormDataParam filename Name of output file to write results to
FormParam encoding The encoding to use in the file: "UTF-8" (default), "ISO-8859-1", "US-ASCII", "UTF-16", "UTF-16BE", "UTF-16LE"
FormParam timeout Timeout in milliseconds (default 1000)

Description

Sets the output filename for the Hub Service to write results to. If no encoding is specified, UTF-8 is used.

If it fails to lock the engine for timeout milliseconds it will wait 2 seconds before trying again. Timeout should be non-zero to avoid deadlocking the engine.

 

DELETE /matchITHub/engines/<engine>/results

Request

Type Name Description
PathParam engine The id of the engine to modify

Description

The output buffer is cleared; any buffered results are lost.

 
 

Lookup

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
POST lookup Look up a record.
Form data: data=<data>
recordLimit=<recordLimit>
timeLimit=<timeLimit>
timeout=<timeout>
GET tables/1/?data=<data> Same as lookup

 

POST /matchITHub/engines/<engine>/lookup data=<data>, recordLimit=<recordLimit>, timeLimit=<timeLimit>, timeout=<timeout>

Request

Type Name Description
PathParam engine The id of the engine to modify
FormParam data A data record to lookup
FormParam recordLimit Maximum number of results to return (default 0 - no limit)
FormParam timeLimit Maximum time (seconds) to wait for a lookup query
FormParam timeout Timeout in milliseconds (default 1000)

 

Response

Name Value Description
count <count> Count of results
result <result records> Array of result records

 

Description

Equivalent to adding data to table 2 and repeatedly calling RESULTS/NEXT.

The timeLimit parameter specifies how long the service should wait for Hub to finish processing the query before fetching the results.

If it fails to lock the engine for timeout milliseconds you may get some empty strings in the results.

The count in the response is the number of matches that matchIT Hub found. If I record limit was specified the result array may contain fewer records.

 

GET /matchITHub/engines/<engine>/table/1?data=<data>, recordLimit=<recordLimit>, timeLimit=<timeLimit>

Request

Type Name Description
PathParam engine The id of the engine to modify
QueryParam data A data record to lookup
FormParam recordLimit Maximum number of results to return (default 0 - no limit)
FormParam timeLimit Maximum time (seconds) to wait for a lookup query

Response

Name Value Description
count <count> Count of results
result <result records> Array of result records

Description

Same as POST lookup. Equivalent to adding data to table 2 and repeatedly calling RESULTS/NEXT.

E.g.

 
 
 

Statistics

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
GET stats Return summary statistics

GET /matchITHub/engines/<engine>/stats

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
stats <xml string> Xml stats string

Description

Produces and returns an XML-formatted string that lists useful statistical details for the current processing mode.

E.g.

 
 
 

Information

 

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
GET version Return the version number
GET expiry Return expiry date

 

GET /matchITHub/engines/<engine>/version

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
version <version number> Hub version number

Description

Returns a string representing the version number of the matchIT Hub engine.

The version consists of four delimited numbers (product.major.minor.patch) plus an optional pre-release indicator, for example "1.0.3.2" or "1.1.0.0 (beta 2)".

E.g.

GETversion.png
 

GET /matchITHub/engines/<engine>/expiry

Request

Type Name Description
PathParam engine The id of the engine to query

Response

Name Value Description
expiry <expiry date> Hub activation code expiry date

Description

Returns an 8-character string of format YYYYMMDD that indicates the expiry date of the applied activation code, for example "20170531".

E.g.

 

GETexpiry.png

 

GET /matchITHub/engines/<engine>/name

Request

engine
Type Name Description
PathParam engine The id number of the engine instance to query

Response

Name Value Description
Name <engine name> The name (if any) associated with the engine instance

Description

Returns the name (if any) associated with the engine instance.

 

GET /matchITHub/engines/<engine>/id

Request

engine
Type Name Description
PathParam engine The name of the engine instance to query

Response

Name Value Description
Name <engine name> The id number of the engine instance

Description

Returns the id number of the engine instance. 

 
 

Errors

Resources relative to http://host:8080/matchITHub/engines/<engine>

REST resource Summary
POST errors Retrieve all error messages as an array

 

POST /matchITHub/engines/<engine>/errors

Request

Type Name Description
PathParam engine The id of the engine to query

 

Response

 
Name Value Description
errorMsgs <error messages> List of error message in an array

Description

Retrieve all error messages as an array. Most methods return the errors immediately, but if you post an input filename or an updates filename an error may occur while the data is being loaded. If that happens the engine state will change to aborted and you can use this method to find out what went wrong.