Migrating from Release v0 API to Planning v1 API

I am using the GET /releases v0 endpoint

This is the endpoint to list all the releases since a specific time. It is replaced with GET /v1/plannings?released_since={date-time}. You can find the full specification of the new v1 endpoint here.

Changes to the Request

Full path of the old URL: GET https://api.conundra.eu/planning/v0/releases?released_since=2024-11-29T10:00:00.000Z

Full path of the new URL: GET https://api.conundra.eu/planning/v1/plannings?released_since=2024-11-29T10:00:00.000Z

Changes

The version changed from v0 to v1
The resource path changed from releases to plannings

Notes

The v1 endpoint can also be used to fetch non-released plannings. The released_since parameter is optional, and if not specified the endpoint will return all plannings.
The v1 endpoint is limited by default to 100 results and uses cursor based paging to fetch additional pages.

Changes to the Response

Old response:

Copy

Copied

{
  "releases": [
    {
      "release_metadata": {
        "planning_business_id": "86b54c9d-21d7-4b37-af3d-25f03886153b",
        "released_at": "2024-11-30T10:00:00Z"
      }
    }
  ]
}

New Response:

Copy

Copied

{
  "plannings": [
    {
      "id": "86b54c9d-21d7-4b37-af3d-25f03886153b",
      "created_at": "2024-11-30T08:15:00Z",
      "released_at": "2024-11-30T10:00:00Z"
    }
  ],
  "cursor": {
    "self": "c2VsZl9fcGFnZQ",
    "prev": "cHJldmlvdXNfX3BhZ2U",
    "next": "bmV4dF9fcGFnZQ"
  }
}

Changes

The top level property in the response is now the plannings array, so:
- releases[].release_metadata.planning_business_id replaced by plannings[].id
- releases[].release_metadata.released_at replaced by plannings[].released_at

Notes

As mentioned before, the v1 endpoint is using cursor based paging , so the result list is limited and the response contains an extra property cursor , which contains the cursors necessary to fetch additional pages.

I am using the GET /plannings/{id}/releases/latest v0 endpoint

This is the endpoint to fetch the details of the latest release of a given planning. It is replaced with GET /v1/plannings/{id}/releases/latest. You can find the full specification of the new v1 endpoint here.

Changes to the Request

Full path of the old URL: GET https://api.conundra.eu/planning/v0/plannings/86b54c9d-21d7-4b37-af3d-25f03886153b/releases/latest

Full path of the new URL: GET https://api.conundra.eu/planning/v1/plannings/86b54c9d-21d7-4b37-af3d-25f03886153b/releases/latest

Changes

The version changed from v0 to v1

Changes to the Response

Old response:

Copy

Copied

{
  "release_metadata": {
    "planning_business_id": "86b54c9d-21d7-4b37-af3d-25f03886153b",
    "released_at": "2024-11-30T10:00:00"
  },
  "trips": [
    {
      "id": "4f3abf12-23a2-4039-83db-b6dc7935395d",
      "proposed_execution": {
        "executors": [
          {
            "id": "EMP-18",
            "name": "Patrick Simmons"
          }
        ],
        "transport_resources": [
          {
            "id": "TR-14",
            "type": "tractor",
            "license_plate": "2-QBD-124"
          }
        ],
        "custom_data": {
          "shop_manager": "John Smith"
        }
      },
      "stops": [
        {
          "id": "4f3abf12-23a2-4039-83db-b6dc7935395d",
          "location": {
            "business_id": "LOC_001",
            "name": "Conundra (Oosterzele)",
            "type": "CUSTOMER",
            "address": {
              "geo_point": {
                "latitude": 50.9514048,
                "longitude": 3.8067878
              },
              "address_line": "Voordries 41b",
              "city": "Oosterzele",
              "zip_code": "9860",
              "country_code": "BE"
            }
          },
          "deliveries": [
            {
              "order": {
                "business_id": "D_445",
                "description": "special delivery",
                "capacities": [
                  {
                    "type": "weight",
                    "value": 20.02
                  }
                ],
                "custom_data": {
                  "shop_manager": "John Smith"
                }
              },
              "timings": {
                "arrival_at": "2024-12-01T10:30:00Z",
                "earliest_arrival_at": "2024-12-01T10:00:00Z",
                "latest_arrival_at": "2024-12-01T12:00:00Z",
                "service_time": "PT15M",
                "wait_time": "PT30M",
                "departure_at": "2024-12-01T11:15:00Z"
              }
            }
          ],
          "pickups": [
            {
              "order": {
                "business_id": "P_751",
                "description": "special pickup",
                "capacities": [
                  {
                    "type": "weight",
                    "value": 20.02
                  }
                ],
                "custom_data": {
                  "shop_manager": "John Smith"
                }
              },
              "timings": {
                "arrival_at": "2024-12-01T10:30:00Z",
                "earliest_arrival_at": "2024-12-01T10:00:00Z",
                "latest_arrival_at": "2024-12-01T12:00:00Z",
                "service_time": "PT15M",
                "wait_time": "PT30M",
                "departure_at": "2024-12-01T11:15:00Z"
              }
            }
          ],
          "timings": {
            "arrival_at": "2024-12-01T10:30:00Z",
            "service_time": "PT15M",
            "wait_time": "PT30M",
            "departure_at": "2024-12-01T11:15:00Z"
          }
        }
      ],
      "breaks": [
        {
          "at": "2024-12-01T11:15:30Z",
          "duration": "PT45M"
        }
      ]
    }
  ]
}

New Response:

Copy

Copied

{
  "release_metadata": {
    "planning_id": "86b54c9d-21d7-4b37-af3d-25f03886153b",
    "released_at": "2024-11-30T10:00:00"
  },
  "routes": [
    {
      "id": "d2c6013e-9194-46ac-a44c-855abf1176ca",
      "resource_combination": {
        "id": "5a4e8c43-80c0-4d5b-8f7e-32ec94f25d79",
        "employee": {
          "business_id": "EMP-18",
          "name": "Patrick Simmons",
          "custom_data": {
            "shop_manager": "John Smith"
          }
        },
        "transport_resources": [
          {
            "business_id": "TR-14",
            "license_plate": "2-QBD-124",
            "custom_data": {
              "shop_manager": "John Smith"
            }
          }
        ]
      },
      "start": {
        "location": {
          "business_id": "LOC_001",
          "name": "Conundra (Oosterzele)",
          "type": "CUSTOMER",
          "geo_point": {
            "latitude": 50.9514048,
            "longitude": 3.8067878
          },
          "address": {
            "address_line": "Voordries 41b",
            "city": "Oosterzele",
            "zip_code": "9860",
            "country_code": "BE"
          }
        },
        "timings": {
          "arrival_at": "2024-12-01T10:30:00Z",
          "service_time": "PT45M",
          "departure_at": "2024-12-01T11:15:00Z"
        }
      },
      "end": {
        "location": {
          "business_id": "LOC_001",
          "name": "Conundra (Oosterzele)",
          "type": "CUSTOMER",
          "geo_point": {
            "latitude": 50.9514048,
            "longitude": 3.8067878
          },
          "address": {
            "address_line": "Voordries 41b",
            "city": "Oosterzele",
            "zip_code": "9860",
            "country_code": "BE"
          }
        },
        "timings": {
          "arrival_at": "2024-12-01T10:30:00Z",
          "service_time": "PT45M",
          "departure_at": "2024-12-01T11:15:00Z"
        }
      },
      "breaks": [
        {
          "at": "2024-12-01T11:15:30Z",
          "duration": "PT45M"
        }
      ],
      "trips": [
        {
          "stops": [
            {
              "location": {
                "business_id": "LOC_001",
                "name": "Conundra (Oosterzele)",
                "type": "CUSTOMER",
                "geo_point": {
                  "latitude": 50.9514048,
                  "longitude": 3.8067878
                },
                "address": {
                  "address_line": "Voordries 41b",
                  "city": "Oosterzele",
                  "zip_code": "9860",
                  "country_code": "BE"
                }
              },
              "deliveries": [
                {
                  "order": {
                    "business_id": "D_445",
                    "description": "special delivery",
                    "capacities": [
                      {
                        "type": "weight",
                        "value": 20.02
                      }
                    ],
                    "custom_data": {
                      "shop_manager": "John Smith"
                    }
                  },
                  "timings": {
                    "arrival_at": "2024-12-01T10:30:00Z",
                    "earliest_arrival_at": "2024-12-01TT10:00:00Z",
                    "latest_arrival_at": "2024-12-01TT12:00:00Z",
                    "service_time": "PT15M",
                    "wait_time": "PT30M",
                    "departure_at": "2024-12-01TT11:15:00Z"
                  }
                }
              ],
              "pickups": [
                {
                  "order": {
                    "business_id": "P_751",
                    "description": "special pickup",
                    "capacities": [
                      {
                        "type": "weight",
                        "value": 20.02
                      }
                    ],
                    "custom_data": {
                      "shop_manager": "John Smith"
                    }
                  },
                  "timings": {
                    "arrival_at": "2024-12-01T10:30:00Z",
                    "earliest_arrival_at": "2024-12-01T10:00:00Z",
                    "latest_arrival_at": "2024-12-01T12:00:00Z",
                    "service_time": "PT15M",
                    "wait_time": "PT30M",
                    "departure_at": "2024-12-01T11:15:00Z"
                  }
                }
              ],
              "timings": {
                "arrival_at": "2024-12-01T10:30:00Z",
                "service_time": "PT15M",
                "wait_time": "PT30M",
                "departure_at": "2024-12-01T11:15:00Z"
              }
            }
          ]
        }
      ]
    }
  ]
}

Changes

release_metadata.planning_business_id renamed to release_metadata.planning_id . (The contents of this field are still the same)
The root level of the response is now routes instead of trips . The routes in v1 contain 1 or more trips for the route. So the meaning of a trip in v0 is not the same as in v1. In v0 a trip contains all the stops to be executed by the resource_combination (new term, see further). In v1 the route is actually what contains everything to be executed by the resource_combination . So you can see the trip in v0 to be equivalent to route in v1. A route in v1 is then further subdivided in trips, which are independently executable parts. ( see: example )
The proposed_execution on a trip in v0 has been moved and renamed to resource_combination on a route in v1. In v0 a trip was fully executed by the proposed_execution . In v1 a route is fully executed by the resource_combination , so all trips in that route are planned to be executed by that resource_combination . It has been renamed to align more with the term from Resource Management . Other changes to this block are:
- executors has been renamed to employee and has changed from an array to an object, since only 1 employee can be assigned to a resource combination.
- executors.id has been renamed to employee.business_id
- transport_resource.id has been renamed to transport_resource.business_id
- custom_data used to be on the root level of the proposed_execution object in v0, but is now available on employee and on every transport_resource in v1, since specific custom data is possible.
The geo_point was part of the address in v0, but has been moved up 1 level to the location object. This is to avoid confusion about consistency of a geo_point and an address. An address might differ from the actual geo_point due to bad resolving or manual input errors. The geo_point is what is used in the planning process. This change applies to all address objects in v1 ( route.start , route.end , trips.stops )
breaks where on the root trips object in v0 and can now be found on the route object.