Clarify guidance on process recource vs. data resource update.

[tkrop]

In the context of #391 we had stumbled about a very specific problem how to best update resources which leads to multiple discussions (see #391 (comment) and https://github.bus.zalan.do/Sokoban/rutherfordium/pull/17#discussion_r551990) including the API guild meeting.

The core discussion can be summarized by POST vs. PUT vs. PATCH and the idea of distinguishing between process resources and data resources.

[tkrop]

Hi @whiskeysierra @meshcalero, I'm working on my concept to guide by distinguishing on resources. Please give feedback.

The main idea is as follows:

Data resources are resources or properties of resources that represent knowledge or facts, e.g. master data, product data, article reviews, e-mail messages, process documentation. Updates to these resources can happen on external requests and does only change the resource data. It does never trigger subsequent actions or processes except for propagating the changed information to listeners registered to this data resource. Data changes may be rejected to ensure the format or consistency of the changed resource.

Process resources are resources or properties of resources that are involved into (business) processes by reflecting the process state or by providing process control information. Updates to these resources can be external and happen either on the process state to reflect the advancement of the (business) process or on control information to reflect changes in the business process. Changes to the process state or control information must be validated to ensure the correctness of the conducted (business) process. Any change is usually triggering subsequent actions or processes to advance the (business) process further until its final state is reached.

Base on this definition I would see the following guidance for POST vs. PUT vs. PATCH:

Updates to data resources should follow the first three suggestions in the PATCH-guideline:

1. PUT only for very simple, small resources (were only all properties together cover the resource purpose). This follows @whiskeysierra best practices that consumers should only be forced to implement against properties they do not need to know for their purpose.
2. PATCH with JSON Merge Patch as before.
3. PATCH with JSON Patch as before.

Updates to process resources (in my opinion) should follow only the last suggestion in the PATCH-guideline:

1. POST with a proper description of what is happening.

While this suggests to do conduct the POST on the process resource itself, I would change this to conduct the update (change) request on a sub-resource for representing the change requests itself as a process resource: "Changes to process resources should always be conducted by creating another (simple) process resource reflecting the change process created by a change request. The change request itself in this context can be understood as a command to continue the process with a specific context information creating a sub-process."

To simplify this concept when applying it, I would allow

1. untracked process resources (i.e. only POST on the collection endpoint is implemented), and
2. polymorphism of process resources (i.e. different change requests types on one endpoint - even without discriminator).

My main arguments for this suggestion is that updates to process resources are simpler to describe and understand based on this fractal process resources model reflecting the sub-processes. It even allows to mix process resources and data resources in a common resource while separating updates to both classes of properties (i.e. data PUT and PATCH, process POST) making the consequences of a change very clear.

[tkrop]

After talking with @tfrauenstein we extended the perspective to other use cases and resource types (see Improve Guidance on GET / PUT / PATCH / POST - Draft).

[dehora]

(see Improve Guidance on GET / PUT / PATCH / POST - Draft).

Is this a public document or internal to Zalando?

[tfrauenstein]

It is a Zalando internal draft doc.
@tkrop pls. kill the doc and share doc via API Guild agenda, thx.

[tkrop]

@dehora @tfrauenstein I did this intentional in public. The slides have no links, and I did not see a reason to keep this work in progress internal. It explains the reason for the envisioned guideline changes/additions.

[ePaul]

🍰 Happy birthday!

[ePaul]

🍰🍰 Happy birthday again!

[ePaul]

🍰🍰🍰 happy birthday again!

[ePaul]

🍰🍰🍰🍰 Happy birthday!

[ePaul]

🍰 🍰 🍰 🍰 🍰 A very belated happy birthday again!

[ePaul]

🍰 🍰 🍰 🍰 🍰 🍰
Happy birthday!

[ePaul]

Idea: add an introductory text with the definitions of the kinds of resources to the beginning of the URLs section, instead of updating all the rules. Link the (maybe somewhat updated) slide set.