Skip to main content

Syniti Match API - Postman collection

Lauren Wheeler
  • Updated

Quick Start using Postman (Windows environment)

If you have Postman, then you can import our example Postman collection which is an easy way to try out the Hub Service REST methods. 

If you don't already have Postman installed, you can download for free from the following location - https://www.postman.com/downloads/ 

Ensure that you have installed the Hub Service software and then open Postman and choose Import from the top menu bar, then select install from 'Link' and use the following to import the Hub Service Collection:

 

 https://www.postman.com/collections/0b74b328ecf2f4ae02f2

Now click on the Manage Environment icon ManageEnvironment.png and then choose Add. Set the Environment Name to HubServiceComplete and set up the following environment variables using your own Hub Service Activation key instead of the one shown in the screenshot below:

 

 

environmentvars.png

 

 

The Hub Service Collection that we've imported will make use of these environment variables etc. The great thing about the collection is that it lists every method that the Hub Service makes available, allowing you to try things out quickly and see the results without having to write actual code.

For example, work your way through the following requests in the Postman Collection to get a flavor for how it works, use the Send button to send the Requests to the Hub Service:

  • Create Initialized engine - will create a new engine using the activation code specified in your environment variables that you created in Postman.
  • Apply Settings String UK Lookup - configures the Hub service to run in lookup mode - look at the Request Body and you will see the configuration XML that is being sent to the Hub Service method.
  • Add Block of Data table 1 - this request has been configured to send 6 records to the Hub Service and store them in table 1.
  • No More Data table 1 - tells the Hub Service that we have completed loading data into Table 1.
  • Lookup JSON - this will perform a JSON lookup request on the Hub Service. If you look at the Body section of the request, you can see the record that is to be searched for (specified in the appropriate JSON format expected) in the loaded table 1 data. Edit the request and set the minimum score to 80, then choose Send. Once you send the request, the Hub Service will respond with any matching records.
  • Delete Engine - deletes the engine that we used and releases the memory that the Hub Service consumed.

Use Postman to Initiate and Enable User Authentication

The same Postman collection can be used for user authentication.  This can be set up by following the steps below:

  1. A keystore will be required as authentication requires HTTPS. Refer to Advanced Configuration.

  2. Create a service configuration file as described at https://support.syniti.com/hc/en-us/articles/5875456691223-H5-2-REST-Service-Configuration. The configuration should look like:

     <?xml version="1.0" encoding="UTF-8"?>
    <config>
    <service>
    <host>https://localhost:8080</host>
    <keystoreLocation>keystore.jks</keystoreLocation>
    <keystorePassword>password</keystorePassword>

    <authenticate>false</authenticate>

    <credentialLocation>pass.enc</credentialLocation
    <compressionMinSize>1048576</compressionMinSize>
    </service>
    </config>

  3. Start the service.

  4. In Postman Collection, send Users/Add Admin and Users/Add Use” requests.
  5. Stop the service.
  6. In the service configuration file edit the authenticate value:
     <config><service>
    <authenticate>true</authenticate>
    </service></config>
  7. Restart the service.
  8. In Postman Collection, send any request, which should fail (authentication hasn’t been specified).
  9. Click on “HubServiceComplete”. Authorization tab should appear in the main window.
  10. Select Type “Basic Auth”, username {{user}}, password {{pass}} (this assumes that environment variables for user and pass have been specified, example is user=admin, pass=examplepassword123).
  11. Click “Save Collection” in the top right corner.
  12. Run any request, which should now proceed in usual fashion.

To use Postman with a “user” role

  1. Change the environment variables to user=user, pass=examplepassword456, and save.
  2. Run any request, which should only be permitted for GET requests and lookups.

To use Postman with a JWT authentication

  1. Send “Users/Get Token” request (should work with either admin or user).
  2. Copy token string value - e.g., 
     eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoiYWRtaW4iLCJpcCI6IjEyNy4wLjAuMSIsIm5hbWUiOiJhZG1pbiIsImV4cCI6MTYzNDYzOTY2NH0.cv229MluTwPu3uJJVOZB3vGCYOBfutFqhfrkwgPcXIo
  3. Click on “HubServiceComplete”.
  4. Select Type “Bearer Token” and paste token string value into “Token”.
  5. Click “Save Collection” in the top-right corner.
  6. Run any request, which should proceed in similar fashion to basic authentication.

Related articles