Skip to content

Commit 4c9f878

Browse files
[#239] Updated API schema with proper description
1 parent d3e7713 commit 4c9f878

File tree

4 files changed

+111
-9
lines changed

4 files changed

+111
-9
lines changed

src/openklant/components/contactgegevens/api/schema.py

+15-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,21 @@
11
from django.conf import settings
2+
from django.utils.translation import gettext_lazy as _
23

3-
# TODO: write a propper description
4-
description = """
5-
Description WIP.
4+
description = _(
5+
"""
6+
**Warning: Difference between `PUT` and `PATCH`**
7+
8+
Both `PUT` and `PATCH` methods are used to update the fields in a resource,
9+
but there is a key difference in how they handle required fields:
10+
11+
> The `PUT` method requires you to specify **all mandatory fields** when updating a resource.
12+
If any mandatory field is missing, the update will fail.
13+
14+
> The `PATCH` method, on the other hand, allows you to update only the fields you specify.
15+
Some mandatory fields can be left out, and the resource will only be updated with the provided data,
16+
leaving other fields unchanged.
617
"""
18+
)
719

820
custom_settings = {
921
"TITLE": "contactgegevens",

src/openklant/components/contactgegevens/openapi.yaml

+11-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,17 @@ info:
44
version: 1.1.0
55
description: |2
66
7-
Description WIP.
7+
**Warning: Difference between `PUT` and `PATCH`**
8+
9+
Both `PUT` and `PATCH` methods are used to update the fields in a resource,
10+
but there is a key difference in how they handle required fields:
11+
12+
> The `PUT` method requires you to specify **all mandatory fields** when updating a resource.
13+
If any mandatory field is missing, the update will fail.
14+
15+
> The `PATCH` method, on the other hand, allows you to update only the fields you specify.
16+
Some mandatory fields can be left out, and the resource will only be updated with the provided data,
17+
leaving other fields unchanged.
818
contact:
919
1020
url: https://zaakgerichtwerken.vng.cloud

src/openklant/components/klantinteracties/api/schema.py

+46-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,51 @@
11
from django.conf import settings
2+
from django.utils.translation import gettext_lazy as _
23

3-
# TODO: write a propper description
4-
description = """
5-
Description WIP.
4+
description = _(
5+
"""
6+
**Warning: Difference between `PUT` and `PATCH`**
7+
8+
Both `PUT` and `PATCH` methods are used to update the fields in a resource,
9+
but there is a key difference in how they handle required fields:
10+
11+
> The `PUT` method requires you to specify **all mandatory fields** when updating a resource.
12+
If any mandatory field is missing, the update will fail.
13+
14+
> The `PATCH` method, on the other hand, allows you to update only the fields you specify.
15+
Some mandatory fields can be left out, and the resource will only be updated with the provided data,
16+
leaving other fields unchanged.
17+
"""
18+
)
19+
partijen_description = _(
20+
"""
21+
**Atomicity in Partij and PartijIdentificator**
22+
23+
Starting from version **2.7.0**, the `Partij` endpoint has been modified to handle
24+
`PartijIdentificator` objects more effectively,
25+
allowing them to be processed within the same request.
26+
This ensures that both entities are handled atomically, preventing incomplete,
27+
and offering better control over the uniqueness of `PartijIdentificator` objects.
28+
29+
For `POST`, `PATCH`, and `PUT` requests for `Partij`,
30+
it is possible to send a list of `PartijIdentificator` objects.
31+
32+
**Warnings:**
33+
34+
- In all requests, `PartijIdentificator` objects should not contain the **UUID**
35+
of the parent `Partij`, because it is automatically assigned.
36+
- `POST` request:
37+
- If the **UUID** is provided in the `PartijIdentificator` object,
38+
the endpoint will treat it as an update operation for the existing `PartijIdentificator`,
39+
applying the provided data and linking the parent `Partij` to the new one created.
40+
- If the **UUID** is **not** specified, the system will create a new resource
41+
for the `PartijIdentificator` respecting all uniqueness constraints.
42+
- `PATCH` or `PUT` requests:
43+
- If the **UUID** is provided in the `PartijIdentificator` object,
44+
the system will update the specified resource with the new data.
45+
- If the **UUID** is **not** specified, the system will `DELETE` all `PartijIdentificator`
46+
objects related to the parent and `CREATE` new ones with the passed data.
647
"""
48+
)
749

850
custom_settings = {
951
"TITLE": "klantinteracties",
@@ -22,7 +64,7 @@
2264
{"name": "klanten contacten"},
2365
{"name": "onderwerpobjecten"},
2466
{"name": "partij-identificatoren"},
25-
{"name": "partijen"},
67+
{"name": "partijen", "description": partijen_description},
2668
{"name": "rekeningnummers"},
2769
{"name": "vertegenwoordigingen"},
2870
],

src/openklant/components/klantinteracties/openapi.yaml

+39-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,17 @@ info:
44
version: 0.1.0
55
description: |2
66
7-
Description WIP.
7+
**Warning: Difference between `PUT` and `PATCH`**
8+
9+
Both `PUT` and `PATCH` methods are used to update the fields in a resource,
10+
but there is a key difference in how they handle required fields:
11+
12+
> The `PUT` method requires you to specify **all mandatory fields** when updating a resource.
13+
If any mandatory field is missing, the update will fail.
14+
15+
> The `PATCH` method, on the other hand, allows you to update only the fields you specify.
16+
Some mandatory fields can be left out, and the resource will only be updated with the provided data,
17+
leaving other fields unchanged.
818
contact:
919
1020
url: https://zaakgerichtwerken.vng.cloud
@@ -5711,5 +5721,33 @@ tags:
57115721
- name: onderwerpobjecten
57125722
- name: partij-identificatoren
57135723
- name: partijen
5724+
description: |2
5725+
5726+
**Atomicity in Partij and PartijIdentificator**
5727+
5728+
Starting from version **2.7.0**, the `Partij` endpoint has been modified to handle
5729+
`PartijIdentificator` objects more effectively,
5730+
allowing them to be processed within the same request.
5731+
This ensures that both entities are handled atomically, preventing incomplete,
5732+
and offering better control over the uniqueness of `PartijIdentificator` objects.
5733+
5734+
For `POST`, `PATCH`, and `PUT` requests for `Partij`,
5735+
it is possible to send a list of `PartijIdentificator` objects.
5736+
5737+
**Warnings:**
5738+
5739+
- In all requests, `PartijIdentificator` objects should not contain the **UUID**
5740+
of the parent `Partij`, because it is automatically assigned.
5741+
- `POST` request:
5742+
- If the **UUID** is provided in the `PartijIdentificator` object,
5743+
the endpoint will treat it as an update operation for the existing `PartijIdentificator`,
5744+
applying the provided data and linking the parent `Partij` to the new one created.
5745+
- If the **UUID** is **not** specified, the system will create a new resource
5746+
for the `PartijIdentificator` respecting all uniqueness constraints.
5747+
- `PATCH` or `PUT` requests:
5748+
- If the **UUID** is provided in the `PartijIdentificator` object,
5749+
the system will update the specified resource with the new data.
5750+
- If the **UUID** is **not** specified, the system will `DELETE` all `PartijIdentificator`
5751+
objects related to the parent and `CREATE` new ones with the passed data.
57145752
- name: rekeningnummers
57155753
- name: vertegenwoordigingen

0 commit comments

Comments
 (0)