API tooling

Overview

The Pick-up and Delivery Routing API follows the OpenAPI specification, which makes it compatible with a wide range of developer tooling. Refer to Using the OpenAPI spec to learn how to access the spec.

Use a code generation tool when you need a typed client library in a specific programming language. Use Postman or Bruno when you want to explore and test the API interactively without writing code.

Generating a code client

Not all generator options and language combinations are verified against the Pick-up and Delivery Routing spec. Timefold provides support for client generation on a best-effort basis.

You can use any OpenAPI-compatible code generation tool to generate an API client in the language of your choice, including Java, Python, TypeScript, and many others. Because client generation is supported for a wide range of languages through these tools, Timefold doesn’t maintain a dedicated API client library.

Using OpenAPI Generator

OpenAPI Generator is a popular option that supports many target languages and libraries.

Download the raw OpenAPI spec and pass it to the generator tool along with the target language and library.

Via CLI / Docker

The OpenAPI Generator CLI can be run as a standalone tool or as a Docker container without a local installation.

docker run --pull always --rm --user $(id -u) \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/openapi.json \
  -g java \
  -o /local/out/java

  • The -i flag specifies the input spec.

  • -g specifies the target generator (language).

  • -o specifies the output directory.

  • The spec file and output directory are mounted from the current directory via -v.

  • --pull always ensures you use the latest image.

  • --user $(id -u) ensures generated files are owned by the current user.

Java generator configuration

When generating a Java client, specific configuration is required because of how the spec models GeoJSON geometry types. This configuration applies regardless of which mode you use to run the generator.

Prerequisites

Version 7.22.0 introduced the REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING normalizer option that is required for correct code generation.

Required configuration

Set the REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING normalizer option to true.

Without this option, the generated Java code may fail to compile due to name clashes on the coordinates field across the Point, Polygon, and MultiPolygon types.

Via CLI / Docker
docker run --pull always --rm --user $(id -u) \
  -v "${PWD}:/local" \
  openapitools/openapi-generator-cli generate \
  -i /local/openapi.json \
  -g java \
  --openapi-normalizer REPLACE_ONE_OF_BY_DISCRIMINATOR_MAPPING=true \
  --library apache-httpclient \
  -o /local/out/java
Workarounds to avoid

Don’t remove allOf references from subtypes as a workaround for compilation errors. Removing these references breaks polymorphism in the generated client code. Specifically, it prevents adding Polygon instances into Vehicle.requiredArea and FixedBreak instances into VehicleShift.requiredBreaks. Use the normalizer option described above instead.

Postman

Postman is a widely used API client for exploring, testing, and sharing API requests through a graphical interface. Importing the OpenAPI spec generates a ready-to-use collection of all endpoints, so you can start making calls without writing any code.

See the Postman OpenAPI documentation for instructions on how to import the spec.

Bruno

Bruno is an offline-first API client that stores collections as plain-text files. Because collections live on disk, they can be committed to Git alongside your code, making it easy to version-control your API requests and collaborate with teammates.

See the Bruno OpenAPI converter documentation for instructions on how to import the spec.

Next