Add C8 REST guidelines

[tmetzke]

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]

👋 🤖 🤔 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]

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?

[akeller]

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

[pepopowitz]

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]

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

[pepopowitz]

@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.

1. Am I correct in thinking from is probably an index to start from? e.g. from: 11 means start at the 11th item.
2. If I am correct, is that a zero-based index or 1-based?
3. Do you think we should describe that here, since we covered the other fields?

[pepopowitz]

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]

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]

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]

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]

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]

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?

[akeller]

I would recommend turning this into a table.

[christinaausley]

@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)

[github-actions]

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

[danielkelemen]

🔧 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}
	}