Mark C8 API as eventually consistent

[tmetzke]

Description

There are two types of C8 API endpoints:

1. Real-time interactions, e.g. updating user tasks, activating jobs, and correlating messages.
2. Near real-time interactions, i.e., everything related to exported data like entity search and get requests.

With camunda/camunda-docs#4580, we'll introduce general guidance on API concepts, including data fetching that touches on the differences in real-time and near real-time data.

Looking at the overview and details of entity endpoints in our API specification, this is not easily distinguishable.

Acceptance criteria

• There is a hint in endpoints with eventual consistency guarantees, making me aware of this and linking to more detailed information.
• Our OpenAPI spec does not include internal docusaurus-style links to reference documents (as external OpenAPI users cannot easily access them).

Possible solutions

• Add custom properties to endpoints with eventual consistency that are picked up by custom docusaurus automation when we generate our reference documentation
• Add a predefined piece of description to endpoints with eventual consistency so OpenAPI consumers have this information.
  • This piece can be elaborate enough to understand the issue already. The reference documentation doesn't have to add anything on top.
  • This can be a bare minimum description that doesn't clutter the OpenAPI spec too much. In our reference documentation generation, we pick this up automatically and replace it with a more elaborate note with links and whatever we find suitable.