From 0b96b45605e9510af35cbc0c9e9b99bf9b60252d Mon Sep 17 00:00:00 2001 From: Daniel Mursa Date: Fri, 7 Mar 2025 10:17:02 +0100 Subject: [PATCH] [#239] Updated API schema with proper description --- .../components/contactgegevens/api/schema.py | 18 +++++-- .../components/contactgegevens/openapi.yaml | 12 ++++- .../components/klantinteracties/api/schema.py | 50 +++++++++++++++++-- .../components/klantinteracties/openapi.yaml | 40 ++++++++++++++- 4 files changed, 111 insertions(+), 9 deletions(-) diff --git a/src/openklant/components/contactgegevens/api/schema.py b/src/openklant/components/contactgegevens/api/schema.py index d0e0f5fb..9bf3bd40 100644 --- a/src/openklant/components/contactgegevens/api/schema.py +++ b/src/openklant/components/contactgegevens/api/schema.py @@ -1,9 +1,21 @@ from django.conf import settings +from django.utils.translation import gettext_lazy as _ -# TODO: write a propper description -description = """ -Description WIP. +description = _( + """ +**Warning: Difference between `PUT` and `PATCH`** + +Both `PUT` and `PATCH` methods are used to update the fields in a resource, +but there is a key difference in how they handle required fields: + +> The `PUT` method requires you to specify **all mandatory fields** when updating a resource. +If any mandatory field is missing, the update will fail. + +> The `PATCH` method, on the other hand, allows you to update only the fields you specify. +Some mandatory fields can be left out, and the resource will only be updated with the provided data, +leaving other fields unchanged. """ +) custom_settings = { "TITLE": "contactgegevens", diff --git a/src/openklant/components/contactgegevens/openapi.yaml b/src/openklant/components/contactgegevens/openapi.yaml index f354379d..11fc02bc 100644 --- a/src/openklant/components/contactgegevens/openapi.yaml +++ b/src/openklant/components/contactgegevens/openapi.yaml @@ -4,7 +4,17 @@ info: version: 1.1.0 description: |2 - Description WIP. + **Warning: Difference between `PUT` and `PATCH`** + + Both `PUT` and `PATCH` methods are used to update the fields in a resource, + but there is a key difference in how they handle required fields: + + > The `PUT` method requires you to specify **all mandatory fields** when updating a resource. + If any mandatory field is missing, the update will fail. + + > The `PATCH` method, on the other hand, allows you to update only the fields you specify. + Some mandatory fields can be left out, and the resource will only be updated with the provided data, + leaving other fields unchanged. contact: email: standaarden.ondersteuning@vng.nl url: https://zaakgerichtwerken.vng.cloud diff --git a/src/openklant/components/klantinteracties/api/schema.py b/src/openklant/components/klantinteracties/api/schema.py index 47a03c9f..13062e00 100644 --- a/src/openklant/components/klantinteracties/api/schema.py +++ b/src/openklant/components/klantinteracties/api/schema.py @@ -1,9 +1,51 @@ from django.conf import settings +from django.utils.translation import gettext_lazy as _ -# TODO: write a propper description -description = """ -Description WIP. +description = _( + """ +**Warning: Difference between `PUT` and `PATCH`** + +Both `PUT` and `PATCH` methods are used to update the fields in a resource, +but there is a key difference in how they handle required fields: + +> The `PUT` method requires you to specify **all mandatory fields** when updating a resource. +If any mandatory field is missing, the update will fail. + +> The `PATCH` method, on the other hand, allows you to update only the fields you specify. +Some mandatory fields can be left out, and the resource will only be updated with the provided data, +leaving other fields unchanged. +""" +) +partijen_description = _( + """ +**Atomicity in Partij and PartijIdentificator** + +Starting from version **2.7.0**, the `Partij` endpoint has been modified to handle +`PartijIdentificator` objects more effectively, +allowing them to be processed within the same request. +This ensures that both entities are handled atomically, preventing incomplete, +and offering better control over the uniqueness of `PartijIdentificator` objects. + +For `POST`, `PATCH`, and `PUT` requests for `Partij`, +it is possible to send a list of `PartijIdentificator` objects. + +**Warnings:** + +- In all requests, `PartijIdentificator` objects should not contain the **UUID** +of the parent `Partij`, because it is automatically assigned. +- `POST` request: + - If the **UUID** is provided in the `PartijIdentificator` object, + the endpoint will treat it as an update operation for the existing `PartijIdentificator`, + applying the provided data and linking the parent `Partij` to the new one created. + - If the **UUID** is **not** specified, the system will create a new resource + for the `PartijIdentificator` respecting all uniqueness constraints. +- `PATCH` or `PUT` requests: + - If the **UUID** is provided in the `PartijIdentificator` object, + the system will update the specified resource with the new data. + - If the **UUID** is **not** specified, the system will `DELETE` all `PartijIdentificator` + objects related to the parent and `CREATE` new ones with the passed data. """ +) custom_settings = { "TITLE": "klantinteracties", @@ -22,7 +64,7 @@ {"name": "klanten contacten"}, {"name": "onderwerpobjecten"}, {"name": "partij-identificatoren"}, - {"name": "partijen"}, + {"name": "partijen", "description": partijen_description}, {"name": "rekeningnummers"}, {"name": "vertegenwoordigingen"}, ], diff --git a/src/openklant/components/klantinteracties/openapi.yaml b/src/openklant/components/klantinteracties/openapi.yaml index 56aa7ff3..0a87c5dc 100644 --- a/src/openklant/components/klantinteracties/openapi.yaml +++ b/src/openklant/components/klantinteracties/openapi.yaml @@ -4,7 +4,17 @@ info: version: 0.1.0 description: |2 - Description WIP. + **Warning: Difference between `PUT` and `PATCH`** + + Both `PUT` and `PATCH` methods are used to update the fields in a resource, + but there is a key difference in how they handle required fields: + + > The `PUT` method requires you to specify **all mandatory fields** when updating a resource. + If any mandatory field is missing, the update will fail. + + > The `PATCH` method, on the other hand, allows you to update only the fields you specify. + Some mandatory fields can be left out, and the resource will only be updated with the provided data, + leaving other fields unchanged. contact: email: standaarden.ondersteuning@vng.nl url: https://zaakgerichtwerken.vng.cloud @@ -5711,5 +5721,33 @@ tags: - name: onderwerpobjecten - name: partij-identificatoren - name: partijen + description: |2 + + **Atomicity in Partij and PartijIdentificator** + + Starting from version **2.7.0**, the `Partij` endpoint has been modified to handle + `PartijIdentificator` objects more effectively, + allowing them to be processed within the same request. + This ensures that both entities are handled atomically, preventing incomplete, + and offering better control over the uniqueness of `PartijIdentificator` objects. + + For `POST`, `PATCH`, and `PUT` requests for `Partij`, + it is possible to send a list of `PartijIdentificator` objects. + + **Warnings:** + + - In all requests, `PartijIdentificator` objects should not contain the **UUID** + of the parent `Partij`, because it is automatically assigned. + - `POST` request: + - If the **UUID** is provided in the `PartijIdentificator` object, + the endpoint will treat it as an update operation for the existing `PartijIdentificator`, + applying the provided data and linking the parent `Partij` to the new one created. + - If the **UUID** is **not** specified, the system will create a new resource + for the `PartijIdentificator` respecting all uniqueness constraints. + - `PATCH` or `PUT` requests: + - If the **UUID** is provided in the `PartijIdentificator` object, + the system will update the specified resource with the new data. + - If the **UUID** is **not** specified, the system will `DELETE` all `PartijIdentificator` + objects related to the parent and `CREATE` new ones with the passed data. - name: rekeningnummers - name: vertegenwoordigingen