# 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](/apis/plannings/planning-api/plannings). ### 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](https://developer.conundra.eu/developer-portal/cursor-paging/) to fetch additional pages. ### Changes to the Response Old response: ``` { "releases": [ { "release_metadata": { "planning_business_id": "86b54c9d-21d7-4b37-af3d-25f03886153b", "released_at": "2024-11-30T10:00:00Z" } } ] } ``` New Response: ``` { "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](https://developer.conundra.eu/developer-portal/cursor-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](https://developer.conundra.eu/planning/v1.0.0#operation/getLatestReleaseByPlanningId). ### 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: ``` { "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: ``` { "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](/developer-portal/planning#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](/developer-portal/resource-management/domain#resource-combination). 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.