(BSR) docs: Add deprecation warning for beginningDatetime field in co…

…llective public api
pass-culture · Jan 14, 2025 · b214143 · b214143
1 parent 52b6449
commit b214143
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 5 deletions.
diff --git a/api/documentation/src/pages/change-logs.md b/api/documentation/src/pages/change-logs.md
@@ -13,6 +13,22 @@ title: Pass Culture API change logs
 **You can find a migration tutorial [here](/docs/tutorials/migrate-to-the-new-api).**
 :::
 
+:::warning
+💡 The `beginningDatetime` field is going to be removed in the following endpoints:
+
+Removed from the return value:
+- [**Get Collective Offer endpoint**](/rest-api#tag/Collective-Offers/operation/GetCollectiveOfferPublic)
+- [**Get Collective Offers endpoint**](/rest-api#tag/Collective-Offers/operation/GetCollectiveOffersPublic)
+
+Removed from the input body and the return value:
+- [**Create Collective Offer endpoint**](/rest-api#tag/Collective-Offers/operation/PostCollectiveOfferPublic)
+- [**Update Collective Offer endpoint**](/rest-api#tag/Collective-Offers/operation/PatchCollectiveOfferPublic)
+
+Please use the `startDatetime` and `endDatetime` fields instead.
+
+The `startDatetime` field will be required when creating a collective offer and its value will be copied to `endDatetime` if `endDatetime` is not provided.
+:::
+
 ## December 2024
 
 ### Individual offers endpoints

diff --git a/api/documentation/static/openapi.json b/api/documentation/static/openapi.json
@@ -1812,7 +1812,7 @@
             "CollectiveOffersResponseModel": {
                 "properties": {
                     "beginningDatetime": {
-                        "description": "Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
+                        "description": "[DEPRECATED - Will be removed in upcoming release. Please use `startDatetime` instead.] Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
                         "example": "2025-07-24T14:00:00+02:00",
                         "title": "Beginningdatetime",
                         "type": "string"
@@ -4139,7 +4139,7 @@
                         "type": "boolean"
                     },
                     "beginningDatetime": {
-                        "description": "Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
+                        "description": "[DEPRECATED - Will be removed in upcoming release. Please use `startDatetime` instead.] Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
                         "example": "2025-07-24T14:00:00+02:00",
                         "title": "Beginningdatetime",
                         "type": "string"
@@ -5732,7 +5732,7 @@
                         "type": "boolean"
                     },
                     "beginningDatetime": {
-                        "description": "Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
+                        "description": "[DEPRECATED - Will be removed in upcoming release. Please use `startDatetime` instead.] Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
                         "example": "2025-07-24T14:00:00+02:00",
                         "format": "date-time",
                         "nullable": true,
@@ -5996,7 +5996,7 @@
                         "type": "boolean"
                     },
                     "beginningDatetime": {
-                        "description": "Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
+                        "description": "[DEPRECATED - Will be removed in upcoming release. Please use `startDatetime` instead.] Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
                         "example": "2025-07-24T14:00:00+02:00",
                         "format": "date-time",
                         "title": "Beginningdatetime",

diff --git a/api/src/pcapi/routes/public/documentation_constants/fields.py b/api/src/pcapi/routes/public/documentation_constants/fields.py
@@ -263,7 +263,7 @@ class SomeOtherResponseModel(BaseModel):
     )
     COLLECTIVE_OFFER_DATE_CREATED = Field(description="Collective offer creation date")
     COLLECTIVE_OFFER_BEGINNING_DATETIME = Field(
-        description="Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
+        description="[DEPRECATED - Will be removed in upcoming release. Please use `startDatetime` instead.] Collective offer beginning datetime. It cannot be a date in the past. The expected format is **[ISO 8601](https://fr.wikipedia.org/wiki/ISO_8601)** (standard format for timezone aware datetime).",
         example=_example_datetime_with_tz,
     )
     COLLECTIVE_OFFER_START_DATETIME = Field(