First REST Request - Connection

This article shows how to send your first REST request to the ADOXX API for simply checking if a successful connection can be made.

The first part shows a simple unauthenticated connection request, the second part focusses on executing a token-based authenticated connection request.

Unauthenticated Connection

The simplest endpoint offered by the ADOXX API is an unauthenticated GET request to the endpoint /rest/connection which simply tests if the REST service responds correctly.

The Java snippet below shows how to send the request.

note

Replace the values in angle brackets with values that fit your setup, e.g. instead of <HOST> use the host at which you access your ADOXX instance.

Click to view the code!

Source Code

public class GetConnection
{
  public static void main (final String [] args) throws ClientProtocolException, IOException
  {
    final CloseableHttpClient aClient = HttpClients.createDefault ();
    final String sPath = "http://<HOST>:<PORT>/ADOXX/rest/connection";
    
    final HttpGet aMethod = new HttpGet (sPath);
    final CloseableHttpResponse aResponse = aClient.execute (aMethod);
    
    try
    {
      final String sResult = EntityUtils.toString (aResponse.getEntity (), "UTF-8");
      final StatusLine aStatusLine = aResponse.getStatusLine ();
      System.out.println ("Status Code: " + aStatusLine.getStatusCode ());
      System.out.println ("Result: \n" + sResult);
    }
    catch (final Exception aEx)
    {
      aEx.printStackTrace ();
    }
    finally
    {
      aResponse.close ();
    }
  }
}

The expected outcome looks similar to the following:

Status Code: 200
Result: 
REST Connection Service Evaluation invoked @ Mon Feb 22 11:38:47 CET 2021

Authenticated Connection

Except for the special unauthenticated connection endpoint, requests will always have to authenticate. To test if authenticated access is working the endpoint /rest/connection/auth can be used.

note

ADOXX RESTful services support three authentication mechanisms. The Java snippet below uses Token Based Authentication. The token is generated using the Util class introduced in First REST Request - Connection.

More sophisticated authentication mechanisms are detailed in the Rest API guide.

The following Java snippet shows a simple Java class containing a static method that creates the security token based on the passed parameters:

Click to view the code!

Source Code

import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.io.Encoders;
import io.jsonwebtoken.security.Keys;

public class Util
{
  public static String createSecurityToken (final String sSecret,
                                            final Map <String, String []> aDataMap) throws UnsupportedEncodingException,
                                                                                   NoSuchProviderException,
                                                                                   NoSuchAlgorithmException,
                                                                                   InvalidKeyException
  {
    final List <byte []> aContent = new ArrayList <byte []> ();
    final List <String> aAllParams = new ArrayList <String> ();
    for (final Entry <String, String []> aEntry : aDataMap.entrySet ())
    {
      aAllParams.add (aEntry.getKey ());
      for (final String sValue : aEntry.getValue ())
      {
        aAllParams.add (sValue);
      }
    }
    aAllParams.add (sSecret);
    
    final Collator aCollator = Collator.getInstance (Locale.US);
    Collections.sort (aAllParams, aCollator);
    
    for (final String aEntry : aAllParams)
    {
      aContent.add (aEntry.getBytes ("UTF-8"));
    }
    
    final String PROVIDER_BOUNCYCASTLE = "BC";
    final String SHA512 = "HMac/SHA512";
    
    if (Security.getProvider (PROVIDER_BOUNCYCASTLE) == null)
    {
      Security.addProvider (new BouncyCastleProvider ());
    }
    final Mac aHmac = Mac.getInstance (SHA512, PROVIDER_BOUNCYCASTLE);
    final SecretKey aKey = new SecretKeySpec (sSecret.getBytes ("UTF-8"), SHA512);
    aHmac.init (aKey);
    aHmac.reset ();
    
    int nSize = 0;
    for (final byte [] aEntry : aContent)
    {
      nSize += aEntry.length;
    }
    final byte [] aAllParamsArray = new byte [nSize];
    int nCount = 0;
    for (final byte [] aEntry : aContent)
    {
      for (final byte aByte : aEntry)
      {
        aAllParamsArray[nCount] = aByte;
        ++nCount;
      }
    }

The following Java snippet shows how to use this class and send an authenticated connection request to the server:

Click to view the code!

Source Code

public class GetConnectionAuth
{
  public static void main (final String [] args) throws ClientProtocolException,
                                                IOException,
                                                InvalidKeyException,
                                                NoSuchAlgorithmException,
                                                NoSuchProviderException
  {
    final CloseableHttpClient aClient = HttpClients.createDefault ();
    
    final String sKey = "<KEY>";
    final String sSecret = "<SECRET>";
    final String sPath = "http://<HOST>:<PORT>/ADOXX/rest/connection/auth";
    
    final Map <String, String []> aTokenParameters = new HashMap <String, String []> ();
    
    final HttpGet aMethod = new HttpGet (sPath);
    
    final long nDate = new Date ().getTime ();
    final String sDate = String.valueOf (nDate);
    final String sGUID = UUID.randomUUID ().toString ();
    
    aMethod.addHeader ("x-axw-rest-identifier", sKey);
    aMethod.addHeader ("x-axw-rest-timestamp", sDate);
    aMethod.addHeader ("x-axw-rest-guid", sGUID);
    
    aTokenParameters.put ("x-axw-rest-timestamp", new String [] {sDate});
    aTokenParameters.put ("x-axw-rest-guid", new String [] {sGUID});
    aTokenParameters.put ("x-axw-rest-identifier", new String [] {sKey});
    
    // Construct the token
    final String sSecurityToken = Util.createSecurityToken (sSecret, aTokenParameters);
    aMethod.addHeader ("x-axw-rest-token", sSecurityToken);
    
    final CloseableHttpResponse aResponse = aClient.execute (aMethod);
    
    try
    {
      final String sResult = EntityUtils.toString (aResponse.getEntity (), "UTF-8");
      final StatusLine aStatusLine = aResponse.getStatusLine ();
      System.out.println ("Status Code: " + aStatusLine.getStatusCode ());
      System.out.println ("Result: \n" + sResult);
    }
    catch (final Exception aEx)
    {
      aEx.printStackTrace ();
    }
    finally
    {
      aResponse.close ();
    }
  }
}

The expected outcome looks similar to the following:

Status Code: 200
Result: 
Authorized Access Granted @ Mon Feb 22 11:40:23 CET 2021