mHUB - API Reference

 

General

Request parameters are of one of the following types.

Argument Types

Type Description
PathParm Argument value included in the URL. e.g. engine in /matchITHub/engines/<engine>
QueryParm Argument indicated following '?' in the URL of a GET. e.g. data in /matchITHub/engines/<engine>/tables/1?data=<data>
FormParm Argument in body of POST with Content-Type: multipart/form-data.
JsonParm Argument in body of POST with Content-Type: application/json.

The following format of response is returned by all requests except "POST results".

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.

Usage Examples

Using a browser:

GETengines.png
 

Using cURL:

curl -X GET http://localhost:8080/matchITHub/engines
{"status":"OK","ids":""}
 

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.

 

Usage Example

Using cURL:

curl -X POST --data "activation_code=<activation_code>" http://localhost:8080/matchITHub/engines
{"status":"OK","engine":1}

Or:

curl -X POST --data-urlencode "activation_code@activation.txt" http://localhost:8080/matchITHub/engines
{"status":"OK","engine":1}

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.

Usage Example

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1
{"status":"OK"}
 

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>

 

Usage Example

Using cURL:

curl -X POST --data "severity=Debug" --data "filename=debuglog.txt" http://localhost:8080/matchITHub/engines/1/log
{"status":"OK"}

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.

 

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1/initialization?activation_code=<activation_code>
{"status":"OK"}

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.

Usage Examples

Using a browser


Using cURL:

curl http://localhost:8080/matchITHub/engines/1/state
{"status":"OK","state":"Initialized:\nthe engine has been initialized but no settings applied"}

 

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.

  

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1/state?state=pause

 

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.

Usage Example

Using cURL:

curl -X POST --data-urlencode "xml=<settings>...</settings>" http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK"}

Or:

curl -X POST --data-urlencode "xml@settings.xml" http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK"}

 

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.

 

Usage Example

Using cURL:

curl -X POST --data-urlencode "file=settings.xml" http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK"}

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.

Usage Examples

Using a browser:

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/settings
{"status":"OK","configXML":"<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n<settings>\n...</settings>"}
 

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.

 

Usage Example

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/settings/advanced
{"status":"OK","configXML":"<?xml version=\"1.0\" encoding=\"utf-8\" ?>\n<settings>\n...</settings>"}
 

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.

 

Usage Example

Using cURL:

curl -X POST --data-urlencode "data=,57,MR,MATTHEW,KASPAR,AVIATION SERVICES INC,14824 BOWE ROAD,BARNWELD,NEW YORK,13304" --data-urlencode "timeout=1000" http://localhost:8080/matchITHub/engines/1/tables/1
{"status":"OK"}

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. The file must be accessible from the service. If adding data from a different machine, post the data in blocks or use the Proxy Engine.

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.

 

Usage Example

Using cURL:

curl -X POST --data-urlencode "filename=D:\testdata\inputfile.txt" --data-urlencode "delimiter=\t" --data-urlencode "encoding=UTF-8" --data "nomore=true" http://localhost:8080/matchITHub/engines/1/tables/1/files
{"status":"OK"}

 

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.

 

Usage Example

Using cURL:

curl -X PUT http://localhost:8080/matchITHub/engines/1/tables/1/eof
{"status":"OK"}

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
unprocessedCount <count> Count of unprocessed records

Description

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

Usage Examples

Using a browser:

 

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/unprocessed
{"status":"OK","unprocessedCount":0}

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.

Usage Examples

Using a browser:


Using cURL:

curl http://localhost:8080/matchITHub/engines/1/tables/1/17
{"status":"OK","result":"\t17\tROBERT HANSEN\tSTATEWEST AIRLINES INC\t4909 EAST MCDOWELL ROAD\tFT COLLINS\tCOLORADO\t80524"}

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.

 

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1/tables/1/17
{"status":"OK"}

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)
HeaderParam async Introduced in v2.0.4.27. Delete table asynchronously (true, false). Defaults to false

 

Description

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

 

Usage Example

Using cURL:

curl -X DELETE -H "async: true" http://localhost:8080/matchITHub/engines/1/tables/2
{"status":"OK"}

 

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.

Usage Example

Using cURL:

curl http://localhost:8080/matchITHub/engines/1/results/count
{"status":"OK","resultCount":0}

 

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.

Usage Example

Using cURL:

curl -X POST --data "timeout=1000" http://localhost:8080/matchITHub/engines/1/results/next
{"status":"OK","result":"\tMG\tlevel\tgroup\tbase_score\ttable\trecord"}

 

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.

 

Usage Example

Using cURL:

curl -X POST --data "timeout=1000" http://localhost:8080/matchITHub/engines/1/results
        MG      I       56      105     0       57
        MG      I       26      118     0       26
        MG      I       26      118     0       35
        MG      I       4       119     0       4
        MG      I       4       119     0       71
        MG      I       10      98      0       10
        MG      I       10      98      0       65
        MG      I       10      98      0       64
        MG      I       80      130     0       80
        MG      I       80      130     0       81
        MG      I       38      103     0       38
        MG      I       38      103     0       63
        MG      I       113     139     0       113
        MG      I       113     139     0       74
        MG      I       15      113     0       15
        MG      I       15      113     0       123

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.

 

Usage Example

Using cURL:

curl -X POST --data "filename=D:\testing\outputfile.txt" http://localhost:8080/matchITHub/engines/1/results/outputfile
{"status":"OK"}

 

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.

 

Usage Example

Using cURL:

curl -X DELETE http://localhost:8080/matchITHub/engines/1/results
{"status":"OK"}
 

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 lookup
Look up a record.
Json: data={<json query>}

 

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 ruleSet see Configuration Guide - Matching Rule Sets
FormParam recordLimit Maximum number of results to return (default 0 - no limit)
FormParam minimumScore Minimum score of results to return (default 0)
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.

 

Usage Example

Using cURL:

curl -X POST --data-urlencode "data=,,JOHN,TATTLE,,,BIRMINGHAM,,B3 3ER" http://localhost:8080/matchITHub/engines/1/lookup
{"status":"OK","results":["\t4\tJOHN TATTLE\tINFORMATION SYSTEMS MANAGER\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t5\t117\t0\t57\t57\t0\t0","\t13\tMR V MACNICHOLS\t\tWETHERALL CONSULTING\t31 DALE END\tBIRMINGHAM\tWEST MIDLANDS\t\tB4 7LH\t4\t27\t0\t27\t27\t0\t4","\t28\tMR G HOOD\t\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t4\t57\t0\t57\t57\t0\t4","\t71\tMR J RATTLE\tIT MANAGER\tFRINTON WILKES LTD\tEDMUND HOUSE\t12 NEWHALL STREET\tBIRMINGHAM\tB3 3ER\t\t1\t97\t0\t57\t57\t0\t4"],"count":4}

GET /matchITHub/engines/<engine>/tables/1?data=<data>, recordLimit=<recordLimit>, minimumScore=<minimumScore>

 

Request

Type Name Description
PathParam engine The id of the engine to modify
QueryParam data A data record to lookup
QueryParam ruleSet see Configuration Guide - Matching Rule Sets
QueryParam recordLimit Maximum number of results to return (default 0 - no limit)
QueryParam minimumScore Minimum score of results to return (default 0)
QueryParam timeout Timeout in milliseconds (default 1000)

 

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.

 
 

POST /matchITHub/engines/<engine>/lookup data=<json query>

From version 2.0.4.

Request

Type Name Description
PathParam engine The id of the engine to modify
JsonParam data A json query

Response

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

Description

Alternative version of POST lookup that takes json as input rather than form data. In the post header specify Content-Type: application/json rather than Content-Type: multipart/form-data

The json query can contain any of the column types specified in Configuration Guide - Appendix A - Column Types and the following:

Name Description
recordLimit Maximum number of results to return (default 0 - no limit)
minimumScore Minimum score of results to return (default 0)
timeout Timeout in milliseconds (default 1000)
ruleSet see Configuration Guide - Matching Rule Sets

 Prior to version 2.0.4.15 the "Array of result records" output was an array of delimited strings. Since verison 2.0.4.15 the "Array of result records" output is an array of json objects, see example below.

Usage Example

Using cURL:

Prior to version 2.0.4.15
curl -X POST -H "Content-Type: application/json" --data "{\"forenames\":\"JOHN\",\"surname\":\"TATTLE\",\"city\":\"BIRMINGHAM\",\"postcode\":\"B3 3ER\"}" http://localhost:8080/matchITHub/engines/lookup/lookup
{"status":"OK","results":["\t4\tJOHN TATTLE\tINFORMATION SYSTEMS MANAGER\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t5\t95\t0\t35\t35\t0\t0","\t73\tJ R MAGSON\tPROD MGR\tFRINTON WILKES LTD\tEDMUND HOUSE\t12/22 NEWHALL STREET\tBIRMINGHAM\tW MIDLANDS\tB3 3ER\t4\t35\t0\t35\t35\t0\t5","\t72\tMR F W BOWER\tMANAGING DIRECTOR\tFRINTON WILKES GROUP\tEDMUND HOUSE\t12/22 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS    B3 3ER\t\t4\t35\t0\t35\t35\t0\t5","\t28\tMR G HOOD\t\tFRINTON WILKES PLC\t12 NEWHALL STREET\tBIRMINGHAM\tWEST MIDLANDS\tB3 3ER\t\t4\t35\t0\t35\t35\t0\t5","\t71\tMR J RATTLE\tIT MANAGER\tFRINTON WILKES LTD\tEDMUND HOUSE\t12 NEWHALL STREET\tBIRMINGHAM\tB3 3ER\t\t5\t75\t0\t35\t35\t0\t5"],"count":5}
Since version 2.0.4.15
curl -X POST -H "Content-Type: application/json" --data "{\"surname\": \"CHILVERS\"}" http://localhost:8080/matchITHub/engines/lookup/lookup
{
   "status":"OK",
   "results":[
      {
         "uniqueref":"1",
         "fullname":"MR G K CHILVERS",
         "jobtitle":"LASER MANAGER",
         "organization":"STANTON COPSHAW DIRECT",
         "address1":"10 EAGLES WOOD BUSINESS PARK",
         "address2":"ALMONDSBURY",
         "address3":"",
         "address4":"BRISTOL",
         "postcode":"BS12 4EU",
         "levels":"13",
         "individualScores":{
            "totalScore":"55",
            "nameScore":"40",
            "organizationScore":"0",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "familyScores":{
            "totalScore":"0",
            "nameScore":"",
            "organizationScore":"",
            "addressScore":"",
            "postcodeScore":""
         },
         "addressScores":{
            "totalScore":"15",
            "nameScore":"0",
            "organizationScore":"0",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "businessScores":{
            "totalScore":"30",
            "nameScore":"0",
            "organizationScore":"15",
            "addressScore":"5",
            "postcodeScore":"10"
         },
         "customScores":{
            "totalScore":"0",
            "nameScore":"",
            "organizationScore":"",
            "addressScore":"",
            "postcodeScore":""
         },
         "key":"1"
      }
   ],
   "count":1
}

 

 

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.

Usage Example

Using cURL:

curl -X POST http://localhost:8080/matchITHub/engines/1/errors
{"status":"OK","errorMsgs":[]}

 

Was this article helpful?
0 out of 0 found this helpful

have a question or not finding what you're looking for?

Submit a ticket to get some help