Add C8 REST guidelines #4580

tmetzke · 2024-11-07T10:57:41Z

Description

Add a public version of the C8 REST API guidelines to help users understand how the C8 REST API works and can be navigated.
Backport the guide to 8.6 to provide general guidance (only those parts present there).
Sort the 8.6 C8 REST API spec categories for better usability.

closes camunda/camunda#24239

When should this change go live?

This is a bug fix, security concern, or something that needs urgent release support.
This is already available but undocumented and should be released within a week.
This on a specific schedule and the assignee will coordinate a release with the DevEx team. (apply hold label or convert to draft PR)
This is part of a scheduled alpha or minor. (apply alpha or minor label)
There is no urgency with this change and can be released at any time.

PR Checklist

My changes are for an already released minor and are in /versioned_docs directory.
My changes are for the next minor and are in /docs directory (aka /next/).
I included my new page in the sidebar file(s).
I added a redirect for a renamed or deleted page to the .htaccess file.

My changes require an Engineering review, and I've assigned the Engineering DRI or delegate.
My changes require a technical writer review, and I've assigned @camunda/tech-writers as a reviewer.

github-actions · 2024-11-07T10:58:05Z

👋 🤖 🤔 Hello, @christinaausley! Did you make your changes in all the right places?

These files were changed only in versioned_docs/version-8.6/. You might want to duplicate these changes in docs/.

versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js

You may have done this intentionally, but we wanted to point it out in case you didn't. You can read more about the versioning within our docs in our documentation guidelines.

pepopowitz

This is great, and I love it. None of my feedback is blocking.

pepopowitz · 2024-11-08T17:47:13Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+
+The API version number does not match the product version (8.x.x). An API’s version is rather defined by the API version number and the product version, e.g. “_POST /v2/user-tasks/search_ in Camunda 8.7.0”.
+
+We do API versioning rather than endpoint versioning, i.e., the version changes for all endpoints if there is a breaking change in at least one endpoint. Multiple versions of an API can exist in a product version to allow for a migration period, e.g. “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”.


non-blocking question that has nothing to do with this PR, and is for my education: is there a v3 coming in 8.7.0, or is this just an example?

Stopping by to add if this is an arbitrary example, please just say "in a future Camunda version" or something less specific.

pepopowitz · 2024-11-08T17:58:06Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+
+## Data fetching
+
+Most resources provide at least one endpoint to fetch related data. Most of those endpoints provide data with near-real time consistency that is queried from exported records, if records for the respective resource are exported by the engine. If resources are not based on exported records, e.g. license data or topology information, the data returned by those endpoints can reflect real time insights or static content.


non-blocking: is there anything to say about the ones that fall outside of the "most"? Is there a general statement we can make about why it is not "all"?

pepopowitz · 2024-11-08T18:02:40Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+
+The **sort** object specifies which fields of the object should be sorted and whether they are sorted in ascending (ASC) or descending (DESC) order.
+
+The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.


This is really helpful, actually...I was going to ask you a question about these fields today anyway. 👍

@tmetzke stopping back after attempting to add spec descriptions for these properties, armed with my new understanding -- one other field that isn't mentioned here is from, an int32.

Am I correct in thinking from is probably an index to start from? e.g. from: 11 means start at the 11th item.

If I am correct, is that a zero-based index or 1-based?

Do you think we should describe that here, since we covered the other fields?

Potentially blocking:

Since these are fields, I think they should be code instead of italic. @christinaausley can probably confirm, but that's how I interpret the code blocks section of the style guide.

Suggested change

The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.

The **page** object details how to slice the result set. An initial search request can omit the page object or define the `limit`. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned `firstItemSortValues` and `lastItemSortValues` of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes `searchAfter` or `searchBefore`.

Also blocking:

The properties in the spec are named firstSortValues and lastSortValues.

Suggested change

The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.

The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstSortValues_ and _lastSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.

pepopowitz · 2024-11-08T18:04:45Z

versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js

-        id: "apis-tools/camunda-api-rest/specifications/get-cluster-topology",
-        label: "Get cluster topology",
-        className: "api-method get",
+        id: "apis-tools/camunda-api-rest/specifications/pin-internal-clock-alpha",


non-blocking, no action requested, informative comment:

Thanks for doing this reordering!

You might be wondering why you had to do it in two places (here, and in the top-level version-8.6-sidbars.json). As tracked in #3027, this particular sidebar.js file is unused by docusaurus, because numbered versions use a static .json file for the top-level sidebars. This file only exists in the 8.6 docs because docusaurus copied it over during versioning, and we never deleted it.

All that to say, any changes in this file will just be ignored. If anything, we should probably delete this file....but that is not your responsibility.

pepopowitz

After I completed my review, I noticed a couple other adjustments that I think we should make. I'm not 100% certain though, so I'm marking this as "commented" rather than "request changes," with hopes that a tech writer can straighten me out.

pepopowitz · 2024-11-08T20:24:25Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+
+The **sort** object specifies which fields of the object should be sorted and whether they are sorted in ascending (ASC) or descending (DESC) order.
+
+The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.


Potentially blocking:

Since these are fields, I think they should be code instead of italic. @christinaausley can probably confirm, but that's how I interpret the code blocks section of the style guide.

Suggested change

The **page** object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.

The **page** object details how to slice the result set. An initial search request can omit the page object or define the `limit`. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned `firstItemSortValues` and `lastItemSortValues` of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes `searchAfter` or `searchBefore`.

pepopowitz · 2024-11-08T20:25:19Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+
+| Operator | Syntax                                    | Description                                                                                                                                               |
+| -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| $eq      | field: { "$eq": value }                   | Filter where field is equal to value. Abbreviated form field: value is also allowed.                                                                      |


Suggested change

| $eq | field: { "$eq": value } | Filter where field is equal to value. Abbreviated form field: value is also allowed. |

| `$eq` | `field: { "$eq": value }` | Filter where field is equal to value. Abbreviated form field: value is also allowed. |

Potentially blocking:

Again, this is my interpretation of the style guide, but I think these bits should all be inline code. (Applies also to many lines that follow this one.)

I noticed a couple things after approving.

tmetzke · 2024-11-11T06:58:33Z

Thanks for the elaborate feedback, @pepopowitz 👍
I'm Zeebe medic this week so I'll have a look at it next week 🙂

akeller

I'm a little confused about the audience for this content. It often reads like something that is only relevant for Camundi and should be tucked into the howtos.

Can you help me understand the intention here?

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

christinaausley · 2024-11-12T21:22:50Z

@tmetzke I made some minor grammatical tweaks and echo the feedback from @pepopowitz.

I'm a little confused about the audience for this content. It often reads like something that is only relevant for Camundi and should be tucked into the howtos.

Can you help me understand the intention here?

@akeller @tmetzke This is a good conversation. I know Tobias wants to version these guidelines, but I'm wondering what alternatives we could consider here.

Regardless of the placement, I will note that this is a lengthy document. We could create a folder and break this into several sub-pages (perhaps in another issue) as follows:

Guidelines (overview)

Naming conventions
Versioning
HTTP status codes & error handling
Data fetching
Search requests
Search responses
Search examples
Date values and variables (or as admonitions in the overview)

danielkelemen · 2024-11-19T11:57:26Z

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

+  "filter": {
+    "assignee": {"$eq": "demo"},
+    "candidateGroups": { "$in": ["groupA", "groupB"] },
+    "variables" : {
+      "orderVolume": 10000,
+      "foo": {"$lt": 500},
+      "bar": {"$exists": false}
+    },
+    "$or": [
+      { "priority": {"$eq": "high"}, "dueDate": { "$lt": "<date>" } },
+      { "priority": {"$eq": "low"}, "followUpDate": { "$lt": "<date>" } }
+    ]


🔧 No $or yet, add multiple conditions.

Suggested change

"filter": {

"assignee": {"$eq": "demo"},

"candidateGroups": { "$in": ["groupA", "groupB"] },

"variables" : {

"orderVolume": 10000,

"foo": {"$lt": 500},

"bar": {"$exists": false}

},

"$or": [

{ "priority": {"$eq": "high"}, "dueDate": { "$lt": "<date>" } },

{ "priority": {"$eq": "low"}, "followUpDate": { "$lt": "<date>" } }

]

"filter": {

"assignee": {"$eq": "demo"},

"candidateGroups": { "$in": ["groupA", "groupB"] },

"variables" : {

"orderVolume": 10000,

"foo": {"$gt": 100, "$lt": 500},

"bar": {"$exists": false}

}

akeller · 2024-12-02T21:58:09Z

@akeller @tmetzke This is a good conversation. I know Tobias wants to version these guidelines, but I'm wondering what alternatives we could consider here.

Who is the audience? Camundi, customers, or both? If we want this to be versioned, but not really available for customers, we can keep it out of the sidebar.

tmetzke · 2024-12-05T06:29:17Z

Thanks, everyone, for your input here, it has not gone unnoticed, I'm just too buzzed up with so many other topics that are blocking other people that I couldn't get to this one here 🙈

akeller · 2024-12-05T17:27:18Z

@christinaausley let's do a little more lifting for @tmetzke. Based on his response here, I can review this a bit to soften some of the Camundi-only guidance and make this more approachable for Camundi and non-Camundi users.

Could you also pull in the suggestions? And turn the error codes into a table format?

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

christinaausley · 2024-12-06T21:36:52Z

@tmetzke Sorry for my delay here. I will give this a thorough review on Monday.

christinaausley · 2024-12-10T18:35:53Z

I have made a handful of formatting and grammatical adjustments -- WDYT?

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md

github-actions · 2024-12-10T20:11:19Z

The preview environment relating to the commit 03bbb7a has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4580/index.html

christinaausley · 2025-01-14T14:20:23Z

@tmetzke How can I best assist you with this? Are you looking for additional review? Can I help close out some of these lingering comments?

tmetzke · 2025-01-14T14:22:22Z

I want to rework this a bit based on previous comments and feedback. I have some ideas but simply get interrupted by too many other topics eventually 😅
It's getting closer to the top of my list currently, so maybe I can finally get an hour or two in for this to improve it 🙈

christinaausley · 2025-01-14T19:18:14Z

@tmetzke Sounds great! Just let me know if you'd like any assistance or to workshop ideas over a call.

tmetzke · 2025-02-10T12:50:36Z

That's how fast a month goes by 🙈
I want to adjust the HTTP status codes list to reflect the current state of 200 and 204, trying to avoid any 202s if possible.

tmetzke · 2025-02-14T11:59:04Z

Notes:

Add a hint that data is always "live" and can "shift" if new data comes in
Add examples for "offset"

tmetzke · 2025-02-24T13:15:42Z

Note:
We added more content to naming conventions, namely:

key and id fields contain the entity as a prefix, for example, userTaskKey, processDefinitionId. This applies when referencing other resources like formKey in the user task entity, in the respective entities themselves like userTaskKey in the user task entity.

The full entity is the prefix to avoid confusion, for example processDefinitionKey instead of processKey (the latter could be interpreted as process instance or process definition).

Other attributes of entities themselves have no prefix to avoid clutter, for example version in the process definition entity. In other resources, they have to be referenced with a prefix, like processDefinitionVersion in the process instance entity.

akeller · 2025-02-24T14:28:23Z

I'm a little confused about the audience for this content. It often reads like something that is only relevant for Camundi and should be tucked into the howtos.

Can you help me understand the intention here?

I noticed this PR will need to be backported (forwardported?) to 8.7. If this content is moved to howtos it becomes unversioned.

However, also looks like this content has shifted (or maybe just my understanding of the project is clearer) and it looks more like content that should be versioned and available for customers (API consumers) as well as API maintainers.

tmetzke · 2025-02-25T09:29:59Z

I'm a little confused about the audience for this content. It often reads like something that is only relevant for Camundi and should be tucked into the howtos.
Can you help me understand the intention here?

I noticed this PR will need to be backported (forwardported?) to 8.7. If this content is moved to howtos it becomes unversioned.

However, also looks like this content has shifted (or maybe just my understanding of the project is clearer) and it looks more like content that should be versioned and available for customers (API consumers) as well as API maintainers.

I'd like to keep it in the versioned docs and adjust it to be valuable for API maintainers and API consumers alike.

tmetzke added 3 commits November 7, 2024 11:57

docs: add public C8 REST API guidelines

9582369

docs: add C8 REST API guidelines to 8.6

8f97e5f

docs: sort 8.6 C8 REST API categories

afc8e72

tmetzke requested review from pepopowitz and a team November 7, 2024 10:57

tmetzke self-assigned this Nov 7, 2024

tmetzke added component:zeebe Issues related with Zeebe project theme:api-streamline Issues related to the theme of streamlining APIs labels Nov 7, 2024

christinaausley requested review from christinaausley and removed request for a team November 7, 2024 11:43

tmetzke added the deploy Stand up a temporary docs site with this PR label Nov 7, 2024

github-actions bot temporarily deployed to camunda-docs November 7, 2024 12:34 Destroyed

docs: adjust 8.6 sidebar for C8 REST API

28c8885

github-actions bot temporarily deployed to camunda-docs November 7, 2024 14:21 Destroyed

pepopowitz previously approved these changes Nov 8, 2024

View reviewed changes

pepopowitz reviewed Nov 8, 2024

View reviewed changes

akeller requested changes Nov 12, 2024

View reviewed changes

akeller reviewed Nov 12, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Outdated Show resolved Hide resolved

style(formatting): grammatical tweaks

e0b223a

github-actions bot temporarily deployed to camunda-docs November 12, 2024 21:34 Destroyed

danielkelemen reviewed Nov 19, 2024

View reviewed changes

akeller reviewed Dec 5, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Outdated Show resolved Hide resolved

akeller reviewed Dec 5, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Outdated Show resolved Hide resolved

akeller reviewed Dec 5, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Show resolved Hide resolved

akeller reviewed Dec 5, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Outdated Show resolved Hide resolved

akeller reviewed Dec 5, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Outdated Show resolved Hide resolved

style(formatting): technical review

a915eb1

github-actions bot temporarily deployed to camunda-docs December 9, 2024 21:20 Destroyed

format

2c700a0

github-actions bot temporarily deployed to camunda-docs December 10, 2024 18:48 Destroyed

christinaausley reviewed Dec 10, 2024

View reviewed changes

docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md Show resolved Hide resolved

add spacing for easier reading

e463261

github-actions bot temporarily deployed to camunda-docs December 10, 2024 20:08 Destroyed

tmetzke mentioned this pull request Dec 19, 2024

Mark C8 API as eventually consistent camunda/camunda#26297

Open

akeller mentioned this pull request Jan 8, 2025

Review the API definition and check naming consistency camunda/camunda#26671

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add C8 REST guidelines #4580

Add C8 REST guidelines #4580

tmetzke commented Nov 7, 2024

github-actions bot commented Nov 7, 2024 •

edited

Loading

pepopowitz left a comment

pepopowitz Nov 8, 2024

akeller Nov 8, 2024

pepopowitz Nov 8, 2024

pepopowitz Nov 8, 2024

pepopowitz Nov 8, 2024 •

edited

Loading

pepopowitz Nov 8, 2024

pepopowitz Nov 8, 2024

pepopowitz Nov 8, 2024

pepopowitz left a comment

pepopowitz Nov 8, 2024

pepopowitz Nov 8, 2024

tmetzke commented Nov 11, 2024

akeller left a comment

christinaausley commented Nov 12, 2024

danielkelemen Nov 19, 2024

akeller commented Dec 2, 2024

tmetzke commented Dec 5, 2024

akeller commented Dec 5, 2024

christinaausley commented Dec 6, 2024

christinaausley commented Dec 10, 2024

github-actions bot commented Dec 10, 2024

christinaausley commented Jan 14, 2025 •

edited

Loading

tmetzke commented Jan 14, 2025

christinaausley commented Jan 14, 2025

tmetzke commented Feb 10, 2025

tmetzke commented Feb 14, 2025

tmetzke commented Feb 24, 2025

akeller commented Feb 24, 2025

tmetzke commented Feb 25, 2025 •

edited

Loading


		The API version number does not match the product version (8.x.x). An API’s version is rather defined by the API version number and the product version, e.g. “_POST /v2/user-tasks/search_ in Camunda 8.7.0”.

		We do API versioning rather than endpoint versioning, i.e., the version changes for all endpoints if there is a breaking change in at least one endpoint. Multiple versions of an API can exist in a product version to allow for a migration period, e.g. “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”.


		## Data fetching

		Most resources provide at least one endpoint to fetch related data. Most of those endpoints provide data with near-real time consistency that is queried from exported records, if records for the respective resource are exported by the engine. If resources are not based on exported records, e.g. license data or topology information, the data returned by those endpoints can reflect real time insights or static content.


		The sort object specifies which fields of the object should be sorted and whether they are sorted in ascending (ASC) or descending (DESC) order.

		The page object details how to slice the result set. An initial search request can omit the page object or define the _limit_. This specifies the maximum number of results to retrieve per request. Subsequent requests can use the value of the returned _firstItemSortValues_ and _lastItemSortValues_ of the [search responses](#search-responses) to page through the items by copying that array into one of the attributes _searchAfter_ or _searchBefore_.

	\| $eq \| field: { "$eq": value } \| Filter where field is equal to value. Abbreviated form field: value is also allowed. \|
	\| `$eq` \| `field: { "$eq": value }` \| Filter where field is equal to value. Abbreviated form field: value is also allowed. \|

Add C8 REST guidelines #4580

Are you sure you want to change the base?

Add C8 REST guidelines #4580

Conversation

tmetzke commented Nov 7, 2024

Description

When should this change go live?

PR Checklist

github-actions bot commented Nov 7, 2024 • edited Loading

pepopowitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz Nov 8, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pepopowitz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tmetzke commented Nov 11, 2024

akeller left a comment

Choose a reason for hiding this comment

christinaausley commented Nov 12, 2024

Choose a reason for hiding this comment

akeller commented Dec 2, 2024

tmetzke commented Dec 5, 2024

akeller commented Dec 5, 2024

christinaausley commented Dec 6, 2024

christinaausley commented Dec 10, 2024

github-actions bot commented Dec 10, 2024

christinaausley commented Jan 14, 2025 • edited Loading

tmetzke commented Jan 14, 2025

christinaausley commented Jan 14, 2025

tmetzke commented Feb 10, 2025

tmetzke commented Feb 14, 2025

tmetzke commented Feb 24, 2025

akeller commented Feb 24, 2025

tmetzke commented Feb 25, 2025 • edited Loading

github-actions bot commented Nov 7, 2024 •

edited

Loading

pepopowitz Nov 8, 2024 •

edited

Loading

christinaausley commented Jan 14, 2025 •

edited

Loading

tmetzke commented Feb 25, 2025 •

edited

Loading