Home Intro Tutorials Articles Rest API Contact
Sign in Try it

Available parts

Step 1: Using the OpenAPI Generator

In this step we will generate TypeScript code that wraps around the REST API and makes it easier for you to interact with the platform.For this we will use the API specification that can be downloaded from the API documentation website.

You can find the API documentation by clicking on the question mark icon in the top right corner of the menu bar.

This will take you to the API documentation website.

At the top of the page, download the xyzt.ai OpenAPI specification by clicking on the Download button.

We will use this openapi.json file to generate TypeScript API code that we will use with node.js to conveniently access the API.

For this you will need to have access to a shell with Node.js installed.

Start by creating a new folder in which you want to store your code:

mkdir rest-api-experiment
cd rest-api-experiment

and copy the downloaded openapi.json into that folder.

Since we’re going to write TypeScript code which will depend on some external npm packages, we start by creating a package.json file. For this, run the following command in the directory you just created (rest-api-experiment). All the other commands mentioned in this tutorial also need to be run from this directory.

npm init -y

This will generate a default package.json file.

Next, install all the required packages: TypeScript and the OpenAPI Generator package. The code that the OpenAPI Generator will generate uses the request package, so install that one as well.

# Install the OpenAPI generator
npm install --save --save-exact @openapitools/openapi-generator-cli@2.5.1
# And the request package needed by the code that the generator generates
npm install --save --save-exact request@2.88.2
npm install --save-dev --save-exact @types/request@2.48.8
# Install TypeScript
npm install --save-dev --save-exact typescript@4.7.4
# And a helper package that provides a base tsconfig.json file
npm install --save-dev --save-exact @tsconfig/recommended@1.0.1

This will update the (dev)dependencies in the package.json file, as well as generate a package-lock.json file and a node_modules folder.

Note that this tutorial uses commands that will install specific versions of packages (the same versions we used to test this tutorial). Normally it should also work with the latest versions of the packages though.

Now, execute the following command to generate the TypeScript models:

# Create a source folder with a gen subfolder
# This makes it easier to exclude the generate code from version control if you want
mkdir -p src/gen

# Use the openapi-generator-cli to generate typescript code for the API schema
# and store the output in the src/gen folder
npx openapi-generator-cli generate \
  -g typescript-node \
  --additional-properties=typescriptThreePlus=true \
  --global-property=skipFormModel=false \
  -o src/gen \
  -i openapi.json

This populates the src/gen folder with the following files and folders:

src/gen
 |_ api.ts
 |_ api
 |  |_ apis.ts
 |  |_ ... (more *.ts files)
 |_ model
 |  |_ createGeoJSONLayerRequest.ts
 |  |_ ... (more *.ts files)
 |_ git_push.sh

as well as some hidden files and folders (for example a .openapi-generator folder).

Congrats, you are now ready to start using the generated API access code.

We recommend using an IDE (Integrated Development Environment) such as IntelliJ IDEA for using the generated code and creating your scripts. This has the benefit that automatic code-completion makes it easy to fill in the necessary parameters.

You can also use your favorite IDE to generate the TypeScript code

Many IDEs (Integrated Development Environment) provide support for OpenAPI code generation. As an example, IntelliJ IDEA has an OpenAPI plugin that can be configured and used as well.

Next part

Go to the next part: Setup and run your first API query