Building a service (Preview)

This page describes features which are only relevant when running Timefold Solver as a service.
The information on these pages may describe functionality which may be changed or even removed in a future release.

Run dataset optimization as a fully isolated service. This opinionated approach builds on Quarkus and eliminates the boilerplate typically needed to expose a solver over a REST API.

If you haven’t done so yet, start with the Getting started: building a service guide.

1. How solving works

Once your service is running, solving is driven entirely through the REST API — no solver management code required.

  1. Submit a problem — POST /<root> with your planning problem as a JSON body. The service registers the dataset, starts optimizing asynchronously, and returns an ID immediately.

  2. Poll for results — GET /<root>/{id} returns the best solution found so far, along with the current score. Call this repeatedly to show progress to the end-user, or once after a known time limit.

  3. Terminate early — DELETE /<root>/{id} stops solving and returns the best solution reached.

  4. Inspect score analysis — GET /<root>/{id}/score-analysis breaks down which constraints are violated and by how much.

See REST API for the full endpoint reference and request/response formats.

2. Built on Timefold Solver (the library)

The service module is not a separate product, it is Timefold Solver with an opinionated runtime on top. Under the hood, the same Solver, SolverManager, constraint streams, and optimization algorithms are running. Everything you know about modeling planning problems and writing constraints transfers directly.

If you are coming from the library, think of the service as the infrastructure layer you no longer have to write yourself: instead of wiring up a SolverManager, a REST endpoint, or thinking about good model ergonomics, the service module provides all of that out of the box.

Your modeling and constraint knowledge is the same, only the plumbing changes.

The following areas of the documentation apply equally to both service and library mode:

Modeling planning problems

How to annotate your domain with @PlanningSolution, @PlanningEntity, @PlanningVariable, and related annotations. This is identical whether you run as a service or embed as a library.

Constraints and Score

How to define hard and soft constraints, choose a score type, and analyze solution quality. Constraint streams and score calculation work identically in both modes.

Tuning and diagnostics

Environment modes, logging, monitoring, multi-threaded solving, and random seed configuration. These concepts and most configuration options apply regardless of how you run the solver.

The pages in this section cover only what is specific to the service module: the REST API contract, model enrichment, constraint weight overrides, demo data, and metrics.