The matchIT Hub Service Use Guide provides information for developers and integrators using matchIT Hub via the RESTful service addon. This document assumes the reader is familiar with the matchIT Hub API.
The matchIT Hub Service is an add-on for mHub that provides the same functionality but in the form of a service rather than an API. The Service is implemented in Java and, on Windows, comes with a Windows Service that runs automatically.
Communication with the service is via a RESTful API which supports all the same methods as the mHub API with the following additions:
- The equivalent of the Hub API applySettings() method allows settings to be applied as a string or by streaming a file
- The equivalent of the Hub API addData() method allows data to be added a single record at a time as a string or added multiple records at a time by streaming a whole delimited file
- The REST API has a "lookup" method that is equivalent to adding data to table 2 and repeatedly calling RESULTS/NEXT
matchIT Hub Service provides a mechanism to hold a master table in memory whilst multiple clients perform lookups or multiple files are overlapped one after another.
The table can be kept up-to-date using the Add, Update and Delete methods.
REST is inspired by HTTP and plays to its strengths. HTTP based RESTful APIs are defined with these aspects:
- base URI, such as http://example.com/resources/
- an Internet media type for the data. This is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)
- standard HTTP methods (e.g., GET, PUT, POST, DELETE, etc)
- hypertext links to reference state
- hypertext links to reference related resources
Well designed RESTful services follow these guidelines:
- use the HTTP verbs (GET, PUT, POST) to mean something
- provide sensible resource names that use a collections metaphor
- use HTTP response codes to indicate status
- offer both JSON and XML response format
The resources of a RESTful service are viewed hierarchically via their URI names. The hierarchical nature is leveraged to imply structure. Resource names are typically nouns, not verbs. The HTTP method specifies the verb portion of a request.
Responses from the matchIT Hub Service are in JSON format.