The ZOLOZ API is language independent and exposed by a gateway service. To integrate the ZOLOZ API, you must firstly ensure you can interact with the ZOLOZ gateway service. This document introduces the method to connect to the ZOLOZ Gateway using the AK/SK approach.

About the task

To interact with the gateway service, you can either integrate the libraries that implement the gateway protocol with ease, or implement the gateway protocol by yourself.

ZOLOZ provides multiple libraries for you to choose based on your programming language and environment:

• Java library: use this library when your programming language is Java.
• Implement the gateway protocol yourself: Implementing the Gateway Protocol to Access ZOLOZ API Yourself.

About the authentication test API

This task uses the authentication test API for demonstration. The Authentication test API is a special API that is not related to any particular product. It is designed for authentication testing purpose. It accepts any valid JSON object, and simply responds with the same JSON object, similar with echo command.

Like other APIs, the authentication test API is also built upon the gateway service, which means after you successfully make a call to the authentication test API, integrating other APIs would be very easy. Additionally, this task provides a sample Postman file, which you can use to send requests and perform API testing via Postman.

Steps

Integrate the ZOLOZ API with libraries

Use the Java library

The ZOLOZ Java library is published on the Maven central repository. The following steps demonstrate how to use the public Java library to interact with the gateway service and call an API.

1. Add the following dependencies to your project's POM file to introduce the ZOLOZ Java library into the project.

<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>1.1.0</version>
</dependency>

API SDK Version: Must be 1.1.0 or later. Please refer here for the latest version of the dependency.

2. Import the OpenApiClient class.

import com.zoloz.api.sdk.client.OpenApiClient;

3. Instantiate an OpenApiClient instance and configure the instance with the API credentials.

Please replace the following fields in the code with your real information. To obtain clientId, accessKey, and secretKey, refer to AK/SK Management.

• clientId: Client ID.
• accessKey/secretKey: A pair of keys used for authentication and authorization.
• setHostUrl: ZOLOZ gateway URL, please refer to Understand environments and service endpoints.

//Set proper values to following vairables
String clientId = "<Client ID>";
String accessKey = "<ACCESS KEY>";
String secretKey = "<SECRET KEY>";

//Instantiate an OpenApiClient object 
OpenApiClient client = new OpenApiClient(); 
client.setHostUrl("<ZOLOZ gateway URL>");
client.setClientId(clientId);
client.setAccessKey(accessKey);
client.setSecretKey(secretKey);

4. Make a call to the API.

//Set the name of authentication test API 
String apiName = "v1.zoloz.authentication.test";

//Set the request, a simple JSON object
String request = "{\"title\": \"hello\", \"description\": \"just for demonstration.\"}";

//Call the API, the response is expected to be a JSON string of the same JSON object
String response = client.callOpenApi(apiName, request);

Implement the Gateway Protocol to Access ZOLOZ API Yourself

When implementing the gateway protocol to access ZOLOZ API yourself, you need to send requests according to the specified message structure. For details, refer to the structure of the request message. Below are the steps to generate a signature using the HmacSHA256 algorithm with the secretKey.

1. Decode the Base64 key
   Use a standard Base64 decoding function that supports URL-safe character sets (i.e., replace + with - and / with _) to convert the secretKey from Base64 encoding into raw byte data.
   Note: Some languages' default Base64 decoders may not support URL-safe characters, in which case manual replacement or the use of a specialized library may be required.
2. Initialize HMAC-SHA256

1. Create an HMAC-SHA256 instance.
2. Pass the decoded byte array as the key to initialize the HMAC-SHA256 algorithm.

Note: The key should be in byte stream format (byte[]), not a string.

3. Calculate the Signature

1. Convert the string to be signed into a byte array using UTF-8 encoding.
2. Use the HMAC-SHA256 algorithm to compute the signature on the byte array to generate the signature result.

4. Encode the Signature Result
   Use the Base64 encoding function to encode the signature result, converting it into a URL-safe Base64 string. Ensure the output conforms to URL-safe format:

• Replace + in Base64 characters with -, and / with _.
• Remove the trailing padding character =.

5. Verify the Signature
   Compare the signature generated by code with the signature generated by Postman to verify consistency.

Use Postman to Test the API

Postman is a commonly used API testing tool, widely utilized for developing, testing, and debugging API interfaces. Below are the detailed steps to perform API testing using Postman:

1. Import the Postman

1. Click here to download the configuration file
2. Open Postman and click Import.
3. Drag and drop the downloaded configuration file into the import window or select the file to upload.

2. Set the Request URL
   Replace the red-colored address with the actual server address for the request.

https://{host}/api/v1/zoloz/authentication/test

3. Configure Authentication Information

1. Open the Pre-request Script tab for the request in Postman.
2. Modify the following three constants.

const ACCESS_KEY = "your Access key";   // Replace with your Access Key
const SECRET_KEY = "your secret key";   // Replace with your Secret Key
const CLIENT_ID = "your client id";     // Replace with your Client ID

4. Execute the API Request

1. Switch to the Body tab and use the default test data to perform the request.

{
    "title": "hello",
    "description": "just for demonstration."
}

1. Click Send to dispatch the request.

5. Check the Test Results

{
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "{\"title\":\"hello\",\"description\":\"just for demonstration.\"}",
        "resultStatus": "S"
    }
}