Guides
AcademyOptiCircleoptimove.com

Generating a Web Inbox client library

Instructions on generating a client library that wraps the Inbox REST API in your favourite language.

Suggest Edits

Prerequisites

📘

The following steps assume you have installed the OpenAPI Generator CLI as a local JAR file. For other installation methods, the command to run may be different, but the options will be the same. See the OpenAPI Generator documentation for more details.

Usage

Create a config.json file:

// config.json
{
  "enumUnknownDefaultCase": true
  // Additional configuration options, see below
}

Then generate a client library for your language with the following command:

java -jar openapi-generator-cli.jar generate \
    -g <TARGET_LANGUAGE> \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

Running this command will create a client library in the specified directory. You can now import this as a library in your project and use it to interact with the Inbox API.

The steps for how to import the generated library into your project will vary by language. The generated library includes a README.md file that gives instructions. Alternatively, you can copy the generated source code directly into your project.

📘

Additional configuration options

Additional configuration options are specified in the config.json file. The available options depend on the target language; the full list of options can be found in the OpenAPI Generator documentation.

For future API compatibility, make sure to set enumUnknownDefaultCase to true.

Many generators allow you to choose between different libraries to use for making HTTP requests etc. You may want to choose a different option based on which libraries your project already uses.

Worked example

The following instructions will get you set up in a Typescript, Java (Android), or Swift (iOS) project.

1. Generate the client library

Create a config.json file to configure properties of the generator. Edit the properties as required, or omit them to use the generator's default values. Make sure to edit the properties relating to publishing the library (package name, repository, etc.).

// config.json
{
  "useObjectParameters": true,
  "enumUnknownDefaultCase": true,
  "supportsES6": false,
  "npmName": "optimove-inbox-api",
  "npmRepository": "https://your-private-npm-repo.com",
  "npmVersion": "1.0"
}

// config.json
{
  "useObjectParameters": true,
  "enumUnknownDefaultCase": true,
  "supportsES6": true,
  "npmName": "optimove-inbox-api",
  "npmRepository": "https://your-private-npm-repo.com",
  "npmVersion": "1.0"
}

// config.json
{
  "groupId": "com.yourcompany",
  "artifactId": "optimove-inbox-api",
  "invokerPackage": "com.yourcompany.optimoveinbox",
  "apiPackage": "com.yourcompany.optimoveinbox.api",
  "modelPackage": "com.yourcompany.optimoveinbox.model",
  "version": "1.0",
  "failOnUnknownProperties": false,
  "enumUnknownDefaultCase": true
}

// config.json
{
  "projectName": "OptimoveInboxApiClient",
  "podVersion": "1.0",
  "enumUnknownDefaultCase": true
}

Then run the generator with the following options:

java -jar openapi-generator-cli.jar generate \
    -g typescript \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

java -jar openapi-generator-cli.jar generate \
    -g java \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

java -jar openapi-generator-cli.jar generate \
    -g swift5 \
    -i <API_URL>/swagger/v1/swagger.json \
    -c config.json \
    -o <OUTPUT_DIRECTORY>

2. Add the library to your project

Typescript

cd <OUTPUT_DIRECTORY>
npm install
npm run build

For production code, we recommend publishing the generated library as a private NPM package, then npm install it in your codebase.

For local development, you can install it as a local package with npm install path/to/generated/lib --save.

Java (Android)

To install the library in your local Maven repository (for development):

cd <OUTPUT_DIRECTORY>
mvn clean install

To deploy the library to a remove Maven repository, configure your repository settings then run:

mvn clean deploy

For Maven projects, add the library dependency in your pom.xml (use the groupId and artifactId you set earlier):

<dependency>
  <groupId>com.yourcompany</groupId>
  <artifactId>optimove-inbox-api</artifactId>
  <version>1.0</version>
  <scope>compile</scope>
</dependency>

For Gradle projects, add the library dependency to your build file:

repositories {
  mavenCentral()    // If you have deployed to Maven central
  mavenLocal()      // If you have deployed to your local Maven repo
}

dependencies {
  implementation "com.yourcompany:optimove-inbox-api:1.0"
}

You can also build the library then manually install the JAR files into your project:

mvn clean package

# JAR files are generated at:
# - target/optimove-inbox-api-1.0.jar
# - target/lib/*.jar

Swift (iOS)

To install the API client as a local dependency in XCode, go to File > Add Package Dependencies.... Click Add Local... and add the directory of the generated library.

For production, you can push the generated library to a Git repository and use that as a dependency for your project.

3. Start using the API!

To retrieve a customer's inbox messages:

import * as inboxApi from "optimove-inbox-api";

const config = inboxApi.createConfiguration();
const api = new inboxApi.MessageApi(config);

async function getUserMessages() {
  const messages = await api.getUserMessages({
    customerId: "customer_id",
    brandId: "your_brand_id",
    tenantId: your_tenant_id,
  });
  
  return messages;
}

// Then call the function elsewhere:
const messages = await getUserMessages();

package com.yourcompany;

import com.yourcompany.optimoveinbox.*;
import com.yourcompany.optimoveinbox.api.*;
import com.yourcompany.optimoveinbox.model.*;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;

public class MessageHelper {
    private MessageApi api;
    private int tenantId;
    private UUID brandId;

    public MessageHelper() {
        ApiClient apiClient = new ApiClient();
        this.api = new MessageApi(apiClient);

        this.tenantId = your_tenant_id;
        this.brandId = UUID.fromString("your_brand_id");
    }

    public List<MessageResponse> getMessages() {
        try {
            List<MessageResponse> messages = this.api.getUserMessages(
              	"customer_id",
              	null, // customer time offset
              	null, // max messages
              	this.tenantId,
              	this.brandId
            );
            return messages;
        } catch (ApiException e) {
            e.printStackTrace();
            return new ArrayList<>();
        }
    }
}

// Then use the class elsewhere:
MessageHelper messageHelper = new MessageHelper();
List<MessageResponse> messages = messageHelper.getMessages();

import OptimoveInboxApiClient

func getUserMessages() async -> [MessageResponse] {
    let tenantId = your_tenant_id
    let brandId = UUID(uuidString: "your_brand_id")
    let customerId = "customer_id"
    
    return await withCheckedContinuation { continuation in
        OptimoveInboxApiClient.MessageAPI.getUserMessages(
            customerId: customerId,
            tenantId: tenantId,
            brandId: brandId,
            completion: { (messagesResponse: [MessageResponse]?, _: (any Error)?) -> Void in
                if let messages = messagesResponse {
                    continuation.resume(returning: messages)
                } else {
                    continuation.resume(returning: [])
                }
            }
        )
    }
}

// Then call the function elsewhere:
let messages = await getUserMessages()

Updated about 1 month ago