Understanding the API
Each model on the Timefold Platform has its own API which conforms with the OpenAPI standard.
1. Explore the model API in the Timefold Platform UI
You can explore the API in Timefold Platform.
-
Log in to app.timefold.ai.
-
Select the model.
-
Select OpenAPI Spec.
1.1. Model API Endpoints
To understand the API endpoints, select an endpoint to expand it. You will see:
-
Parameters: The parameters required by the API endpoint.
-
Request body: For POST endpoints, you can view example values that are accepted as part of the JSON input and the model schema.
-
Response: The responses the API endpoints will return, example values, and the schema.
The Example Value tab for each endpoint show an example of the JSON for that endpoint:
The Schema tab shows the values, their types, and a description. Each field can be expanded to view related information.
1.2. Testing the model APIs
To test the API functionality in the platform, you first need to authorize the API.
-
Via the Tenant drop-down in the top right, select Tenant settings.
-
Navigate to the API Keys section.
-
Create or copy an API key that has permissions for the model you want to test.
-
Navigate back to the model you want to test and select OpenAPI Spec.
-
Click Authorize and paste the API key you just copied.
1.3. Demo datasets
Demo datasets that demonstrate the functionality are available. To view the list of demo datasets:
-
Expand the POST /v1/demo-data endpoint.
-
Click Try it out, then click Execute.
You will see the Curl instructions to request the dataset and the request URL.
You will also see the response to the request with the list of available datasets.
To download one of the listed datasets:
-
Expand the POST /v1/demo-data/{demoDataId} endpoint.
-
Click Try it out, enter the name of the dataset, for instance, "BASIC", and click Execute.
In the response body, you will see the dataset. Copy the dataset to use with subsequent endpoints.
You can also use your own dataset to test the functionality.
1.4. Request a Pick-up and Delivery plan
To request a schedule in the Pick-up and Delivery model:
-
Expand the POST v1/route-plans endpoint, and click Try it out.
-
Paste the dataset from the previous call (or use your own dataset) into the request body field over the existing text and click Execute.
Note the ID in the response.
You can view the dataset as it is being solved by navigating back to the top of the page and clicking Plans. Note, it will take a few minutes to provide a solution for the dataset.
1.5. Request the route plan
To request the solution for the dataset:
-
Expand the GET v1/route-plans/{id} endpoint, and click Try it out.
-
Paste the ID from the previous POST call into the id field.
In the response body, you will see the route plan. Note, if the route plan is still being generated, the solverStatus will be "SOLVING_ACTIVE". If the final route plan has been generated, the solverStatus will be "SOLVING_COMPLETE".
2. Using the OpenAPI
2.1. Create problem dataset
Create problem dataset using predefined model schema that follows OpenAPI specification. The application provides several out-of-the-box examples that can be used as a starting point.
GET /v1/demo-data
GET /v1/demo-data/{dataset_name}
2.2. Submit a dataset
Submit the unsolved dataset using the REST API. The application validates the input and returns a unique identifier of the problem. The solving process is scheduled and eventually starts.
POST /v1/route-plans
2.3. Get current best solution and check status
Check the current best solution and receive information about the solving process.
The solution contains the optimized route plan.
Use id attribute returned by submit a dataset step.
GET /v1/route-plans/{id}
2.4. Terminate solving
Terminate the solving process and receive the current best solution.
Use id attribute returned by submit a dataset step.
DELETE /v1/route-plans/{id}