From 9582369322b49209c69e56a450000ba2662b84a7 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:01:14 +0100 Subject: [PATCH 1/8] docs: add public C8 REST API guidelines --- .../camunda-api-rest-guidelines.md | 309 ++++++++++++++++++ .../camunda-api-rest/sidebar-schema.js | 1 + 2 files changed, 310 insertions(+) create mode 100644 docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md diff --git a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md new file mode 100644 index 00000000000..fdbc0027ba7 --- /dev/null +++ b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -0,0 +1,309 @@ +--- +id: camunda-api-rest-guidelines +title: "Guidelines" +description: "Learn about the basic guidelines , structures, and conventions of the Camunda 8 REST API." +--- + +# API guidelines + +As outlined below in this document, we follow a mix of proposed standards and best practices for RESTful design and implementation consistently across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. + +## Naming conventions + +Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This improves the experience when working across multiple APIs by reducing friction. + +The API overall applies the following naming conventions: + +- We favor **nouns** over verbs, e.g. _assignment_ over _assign_. +- For top-level resources, we use plural terms, e.g. _user-tasks_. +- In path parameters, we use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, e.g. _user-tasks_. +- In query parameters, we use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, e.g. _userTaskKey_. + +All of this can be observed in the following endpoint example: + +> POST /user-tasks/{userTaskKey}/**assignment** + +When working with IDs or similar short two or three-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. + +| term | usage | +| ---- | ------------------------------------------ | +| ID | _id_ (standalone) or _processDefinitionId_ | +| URL | _url_ (standalone) or _externalUrl_ | +| UUID | _uuid_ (standalone) or _clusterUuid_ | + +Identifiers follow a naming rule, in parameters and data attributes alike: + +- Unique technical identifiers are suffixed with **key**, e.g. _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. +- Other identifiers, e.g. copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, e.g. _processDefinitionId_. + +## Versioning + +We use the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, we provide updates to the API in place and only increment the version number when a major, breaking change happens. + +Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. + +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”. + +## HTTP status codes & error handling + +Handling errors has to be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. + +We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: + +- Type +- Status +- Title +- Detail +- Instance + +We use the following error codes and descriptions across our APIs: + +- 200 OK +- 204 No Content +- 400 Bad Request + - Generic error that contains further description in the problem detail. +- 401 Unauthorized + - The client is not authenticated yet. + - The client should try again with a modified Authorization header. +- 403 Forbidden + - The client has incorrect or insufficient permissions for the request. +- 404 Not Found +- 409 Conflict + - The request is trying to modify a resource that is currently not in the right state. +- 412 Precondition failed + - The client should check the cluster status. +- 429 Rate Limited Exceeded + - The client exceeds a defined limit of requests, e.g. Zeebe signaling backpressure due to more requests than the broker can currently process +- 500 Internal Server Error + - Generic error that contains further description in the problem detail. + +Each error code should have clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. + +## 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. + +For most resources, there are search endpoints to query by POST method and a given query request object where applicable. The structure of such query requests always follows the same schema and so does the response, always returning a list of items matching the query criteria. + +[Search requests](#search-requests) are forwarded as queries to the datastores that hold the exported records and the query results are returned in the format described in [search responses](#search-responses). + +Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at _POST /v2/users/search_, a user's groups can be retrieved using _POST /v2/users/{userKey}/groups/search_. Each resource determines independently if subordinate resources can be accessed this way. + +Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, e.g. _GET /v2/users/{userKey}_. + +### Search requests + +Query requests consist of the components for **filter**, **sort**, and **page**. + +The **filter** object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. + +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_. + +``` +{ + "filter": { + + }, + "sort": [ + { "": "" }, + { "": "" } + ], + "page": { + "searchAfter": [ … , … ], + "searchBefore": [ … , … ], + "limit": + } +} +``` + +#### Advanced Search + +To provide an easy yet expressive way for users to search for and filter resources, search requests can contain more advanced filter criteria than fields being _equal_ to a target value. + +For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of supported advanced filter operators is described below. Examples of advanced operators are shown in the [Search example](#search-example). + +##### Conditional operators + +| Operator | Syntax | Description | +| -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| $eq | field: { "$eq": value } | Filter where field is equal to value. Abbreviated form field: value is also allowed. | +| $neq | field: { "$neq": value } | Filter where field is not equal to value. | +| $exists | field: { "$exists": value } | Filter where field does or does not exist. The value is a boolean and can be either true or false. | +| $gt | field: { "$gt": value } | Filter where field is greater than value. Supports numeric and [Date values](#date-values). | +| $gte | field: { "$gte": value } | Filter where field is greater than or equal to value. Supports numeric and [Date values](#date-values). | +| $lt | field: { "$lt": value } | Filter where field is less than value. Supports numeric and [Date values](#date-values). | +| $lte | field: { "$lte": value } | Filter where field is less than or equal to value. Supports numeric and [Date values](#date-values). | +| $like | field: { "$like": value } | Filter where field contains a string like value. Use \* as a placeholder for an arbitrary number of characters anywhere in value. Supports string values. | +| $in | field: { "$in": [ value1, value2, ... ] } | Filter where field is equal to any of the values in the provided array. | + +##### Logical operators + +| Operator | Syntax | Description | +| -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | +| $or | "$or": [ { condition1 }, { condition2 }, ... ] | Filter where at least one of the conditions is true. | +| and | { field: { "$lt": value1 }, field: { "$gt": value2 }, ... } | All conditions outside of $or operators will be considered as combined by an and operator. There is no explicit operator. | + +##### Variable filtering + +Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the _variables_ object and defining filter criteria for specific variables in there. + +In general, the syntax looks as follows: + +``` +POST /v2/user-tasks/search + +{ + "filter": { + "variables" : { + "orderVolume": 10000, + "foo": {"$lt": 500}, + "bar": {"$exists": false} + } + } +} +``` + +This filters for user tasks containing at least the variables _orderVolume_ with a value of _10000_ and _foo_ with a value lower than _500_, and **not** containing variable _bar_. + +For variable values, the filter criteria outlined above for fields can be used. + +### Search responses + +Query responses consist of the components **items** and **page**. + +The **items** object is an array of instances of the respective endpoint’s resource. The attributes of those instances vary by endpoint and are described in the endpoint’s documentation. + +The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The _totalItems_ attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). + +The _firstSortValues_ field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like _searchBefore_ in a [search request](#search-requests). The _lastSortValues_ field provides the same for the **last** entry of this page to allow paging forward using _searchAfter_. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s _sort_ object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute: usually that is the internal record’s key. + +``` +{ + "items": [ + { : , : ... } + { : , : ... } + ], + "page": { + "totalItems": , + "firstSortValues": [ + , + , + ... , + + ], + "lastSortValues": [ + , + , + ... , + + ] + } +} +``` + +### Search example + +Querying for the first 3 user tasks with certain criteria, sorted by state, could look as follows: + +``` +POST /v2/user-tasks/search + +{ + "filter": { + "assignee": {"$eq": "demo"}, + "candidateGroups": { "$in": ["groupA", "groupB"] }, + "variables" : { + "orderVolume": 10000, + "foo": {"$lt": 500}, + "bar": {"$exists": false} + }, + "$or": [ + { "priority": {"$eq": "high"}, "dueDate": { "$lt": "" } }, + { "priority": {"$eq": "low"}, "followUpDate": { "$lt": "" } } + ] + }, + "sort": [ + { "state": "ASC" } + ], + "page": { + "limit": 3 + } +} +``` + +This could yield the following example result: + +``` +200 OK + +{ + "items": [ + { + "state": "CREATED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786345, + ... + }, + { + "state": "CREATED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786456, + ... + }, + { + "state": "COMPLETED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786678, + ... + } + ], + "page": { + "totalItems": 345, + "firstSortValues": [ "CREATED", 22456786345 ] + "lastSortValues": [ "COMPLETED", 22456786678 ] + } +} +``` + +A follow-up request to receive the next 3 items could then look as follows: + +``` +POST /v2/user-tasks/search + +{ + "filter": { + "assignee": {"$eq": "demo"}, + "candidateGroups": { "$in": ["groupA", "groupB"] }, + "variables" : { + "orderVolume": 10000, + "foo": { "$lt": 500 }, + "bar": { "$exists": false } + }, + "$or": [ + { "priority": { "$eq": "high" }, "dueDate": { "$lt": "" } }, + { "priority": { "$eq": "low" }, "followUpDate": { "$lt": "" } } + ] + }, + "sort": [ + { "state": "ASC" } + ], + "page": { + "limit": 3, + "searchAfter": [ "COMPLETED", 22456786678 ] + } +} +``` + +This yields the next 3 user task items after the last one from the first search request’s result. + +## Date values + +All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. + +## Variables + +Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. diff --git a/docs/apis-tools/camunda-api-rest/sidebar-schema.js b/docs/apis-tools/camunda-api-rest/sidebar-schema.js index 465f7ac2831..29277a1c229 100644 --- a/docs/apis-tools/camunda-api-rest/sidebar-schema.js +++ b/docs/apis-tools/camunda-api-rest/sidebar-schema.js @@ -3,6 +3,7 @@ module.exports = { "Camunda 8 API (REST)": [ "apis-tools/camunda-api-rest/camunda-api-rest-overview", + "apis-tools/camunda-api-rest/camunda-api-rest-guidelines", "apis-tools/camunda-api-rest/camunda-api-rest-authentication", { Specifications: require("./specifications/sidebar.js"), From 8f97e5f6837749e151de364b58fc33079785ac53 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Thu, 7 Nov 2024 11:56:10 +0100 Subject: [PATCH 2/8] docs: add C8 REST API guidelines to 8.6 --- .../camunda-api-rest-guidelines.md | 244 ++++++++++++++++++ .../camunda-api-rest/sidebar-schema.js | 1 + 2 files changed, 245 insertions(+) create mode 100644 versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md new file mode 100644 index 00000000000..fc07699134e --- /dev/null +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -0,0 +1,244 @@ +--- +id: camunda-api-rest-guidelines +title: "Guidelines" +description: "Learn about the basic guidelines , structures, and conventions of the Camunda 8 REST API." +--- + +# API guidelines + +As outlined below in this document, we follow a mix of proposed standards and best practices for RESTful design and implementation consistently across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. + +## Naming conventions + +Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This improves the experience when working across multiple APIs by reducing friction. + +The API overall applies the following naming conventions: + +- We favor **nouns** over verbs, e.g. _assignment_ over _assign_. +- For top-level resources, we use plural terms, e.g. _user-tasks_. +- In path parameters, we use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, e.g. _user-tasks_. +- In query parameters, we use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, e.g. _userTaskKey_. + +All of this can be observed in the following endpoint example: + +> POST /user-tasks/{userTaskKey}/**assignment** + +When working with IDs or similar short two or three-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. + +| term | usage | +| ---- | ------------------------------------------ | +| ID | _id_ (standalone) or _processDefinitionId_ | +| URL | _url_ (standalone) or _externalUrl_ | +| UUID | _uuid_ (standalone) or _clusterUuid_ | + +Identifiers follow a naming rule, in parameters and data attributes alike: + +- Unique technical identifiers are suffixed with **key**, e.g. _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. +- Other identifiers, e.g. copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, e.g. _processDefinitionId_. + +## Versioning + +We use the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, we provide updates to the API in place and only increment the version number when a major, breaking change happens. + +Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. + +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”. + +## HTTP status codes & error handling + +Handling errors has to be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. + +We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: + +- Type +- Status +- Title +- Detail +- Instance + +We use the following error codes and descriptions across our APIs: + +- 200 OK +- 204 No Content +- 400 Bad Request + - Generic error that contains further description in the problem detail. +- 401 Unauthorized + - The client is not authenticated yet. + - The client should try again with a modified Authorization header. +- 403 Forbidden + - The client has incorrect or insufficient permissions for the request. +- 404 Not Found +- 409 Conflict + - The request is trying to modify a resource that is currently not in the right state. +- 412 Precondition failed + - The client should check the cluster status. +- 429 Rate Limited Exceeded + - The client exceeds a defined limit of requests, e.g. Zeebe signaling backpressure due to more requests than the broker can currently process +- 500 Internal Server Error + - Generic error that contains further description in the problem detail. + +Each error code should have clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. + +## 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. + +For most resources, there are search endpoints to query by POST method and a given query request object where applicable. The structure of such query requests always follows the same schema and so does the response, always returning a list of items matching the query criteria. + +[Search requests](#search-requests) are forwarded as queries to the datastores that hold the exported records and the query results are returned in the format described in [search responses](#search-responses). + +Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at _POST /v2/users/search_, a user's groups can be retrieved using _POST /v2/users/{userKey}/groups/search_. Each resource determines independently if subordinate resources can be accessed this way. + +Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, e.g. _GET /v2/users/{userKey}_. + +### Search requests + +Query requests consist of the components for **filter**, **sort**, and **page**. + +The **filter** object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. + +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_. + +``` +{ + "filter": { + + }, + "sort": [ + { "": "" }, + { "": "" } + ], + "page": { + "searchAfter": [ … , … ], + "searchBefore": [ … , … ], + "limit": + } +} +``` + +### Search responses + +Query responses consist of the components **items** and **page**. + +The **items** object is an array of instances of the respective endpoint’s resource. The attributes of those instances vary by endpoint and are described in the endpoint’s documentation. + +The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The _totalItems_ attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). + +The _firstSortValues_ field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like _searchBefore_ in a [search request](#search-requests). The _lastSortValues_ field provides the same for the **last** entry of this page to allow paging forward using _searchAfter_. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s _sort_ object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute: usually that is the internal record’s key. + +``` +{ + "items": [ + { : , : ... } + { : , : ... } + ], + "page": { + "totalItems": , + "firstSortValues": [ + , + , + ... , + + ], + "lastSortValues": [ + , + , + ... , + + ] + } +} +``` + +### Search example + +Querying for the first 3 user tasks with certain criteria, sorted by state, could look as follows: + +``` +POST /v2/user-tasks/search + +{ + "filter": { + "assignee": "demo", + "variables" : { + "orderVolume": 10000 + } + }, + "sort": [ + { "state": "ASC" } + ], + "page": { + "limit": 3 + } +} +``` + +This could yield the following example result: + +``` +200 OK + +{ + "items": [ + { + "state": "CREATED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786345, + ... + }, + { + "state": "CREATED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786456, + ... + }, + { + "state": "COMPLETED", + "processInstanceKey": 22456786958, + "userTaskKey": 22456786678, + ... + } + ], + "page": { + "totalItems": 345, + "firstSortValues": [ "CREATED", 22456786345 ] + "lastSortValues": [ "COMPLETED", 22456786678 ] + } +} +``` + +A follow-up request to receive the next 3 items could then look as follows: + +``` +POST /v2/user-tasks/search + +{ + "filter": { + "assignee": "demo", + "variables" : { + "orderVolume": 10000 + } + }, + "sort": [ + { "state": "ASC" } + ], + "page": { + "limit": 3, + "searchAfter": [ "COMPLETED", 22456786678 ] + } +} +``` + +This yields the next 3 user task items after the last one from the first search request’s result. + +## Date values + +All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. + +## Variables + +Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/sidebar-schema.js b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/sidebar-schema.js index 465f7ac2831..29277a1c229 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/sidebar-schema.js +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/sidebar-schema.js @@ -3,6 +3,7 @@ module.exports = { "Camunda 8 API (REST)": [ "apis-tools/camunda-api-rest/camunda-api-rest-overview", + "apis-tools/camunda-api-rest/camunda-api-rest-guidelines", "apis-tools/camunda-api-rest/camunda-api-rest-authentication", { Specifications: require("./specifications/sidebar.js"), From afc8e72be2af09d7f57f87f7b55292963b178083 Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:03:04 +0100 Subject: [PATCH 3/8] docs: sort 8.6 C8 REST API categories --- .../specifications/sidebar.js | 266 +++++++++--------- 1 file changed, 133 insertions(+), 133 deletions(-) diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js index 5aae0ea5757..1cbf7aaaced 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/specifications/sidebar.js @@ -5,235 +5,205 @@ module.exports = [ }, { type: "category", - label: "Cluster", + label: "Clock", items: [ { type: "doc", - 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", + label: "Pin internal clock (alpha)", + className: "api-method put", + }, + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/reset-internal-clock-alpha", + label: "Reset internal clock (alpha)", + className: "api-method post", }, ], }, { type: "category", - label: "License", + label: "Cluster", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/get-status-of-camunda-license", - label: "Get status of Camunda license", + id: "apis-tools/camunda-api-rest/specifications/get-cluster-topology", + label: "Get cluster topology", className: "api-method get", }, ], }, { type: "category", - label: "Job", + label: "Decision definition", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/activate-jobs", - label: "Activate jobs", - className: "api-method post", - }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/fail-job", - label: "Fail job", + id: "apis-tools/camunda-api-rest/specifications/query-decision-definitions-alpha", + label: "Query decision definitions (alpha)", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/report-error-for-job", - label: "Report error for job", - className: "api-method post", + id: "apis-tools/camunda-api-rest/specifications/get-decision-definition-xml-alpha", + label: "Get decision definition XML (alpha)", + className: "api-method get", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/complete-job", - label: "Complete job", + id: "apis-tools/camunda-api-rest/specifications/evaluate-decision", + label: "Evaluate decision", className: "api-method post", }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/update-a-job", - label: "Update a job", - className: "api-method patch", - }, ], }, { type: "category", - label: "Incident", + label: "Decision instance", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/resolve-incident", - label: "Resolve incident", - className: "api-method post", - }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-incidents-alpha", - label: "Query incidents (alpha)", + id: "apis-tools/camunda-api-rest/specifications/query-decision-instances-alpha", + label: "Query decision instances (alpha)", className: "api-method post", }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/get-incident-by-key-alpha", - label: "Get incident by key (alpha)", - className: "api-method get", - }, ], }, { type: "category", - label: "User task", + label: "Decision requirements", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/complete-user-task", - label: "Complete user task", + id: "apis-tools/camunda-api-rest/specifications/query-decision-requirements-alpha", + label: "Query decision requirements (alpha)", className: "api-method post", }, + ], + }, + { + type: "category", + label: "Documents", + items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/assign-user-task", - label: "Assign user task", + id: "apis-tools/camunda-api-rest/specifications/upload-document-alpha", + label: "Upload document (alpha)", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/update-user-task", - label: "Update user task", - className: "api-method patch", + id: "apis-tools/camunda-api-rest/specifications/download-document-alpha", + label: "Download document (alpha)", + className: "api-method get", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/unassign-user-task", - label: "Unassign user task", + id: "apis-tools/camunda-api-rest/specifications/delete-document-alpha", + label: "Delete document (alpha)", className: "api-method delete", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-user-tasks-alpha", - label: "Query user tasks (alpha)", + id: "apis-tools/camunda-api-rest/specifications/create-document-link-alpha", + label: "Create document link (alpha)", className: "api-method post", }, ], }, { type: "category", - label: "Clock", + label: "Element instance", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/pin-internal-clock-alpha", - label: "Pin internal clock (alpha)", - className: "api-method put", - }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/reset-internal-clock-alpha", - label: "Reset internal clock (alpha)", + id: "apis-tools/camunda-api-rest/specifications/update-element-instance-variables", + label: "Update element instance variables", className: "api-method post", }, ], }, { type: "category", - label: "Process instance", + label: "Flow node Instance", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/create-process-instance", - label: "Create process instance", - className: "api-method post", - }, - { - type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-process-instances-alpha", - label: "Query process instances (alpha)", + id: "apis-tools/camunda-api-rest/specifications/query-flow-node-instances-alpha", + label: "Query flow node instances (alpha)", className: "api-method post", }, + ], + }, + { + type: "category", + label: "Incident", + items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/cancel-process-instance", - label: "Cancel process instance", + id: "apis-tools/camunda-api-rest/specifications/resolve-incident", + label: "Resolve incident", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/migrate-process-instance", - label: "Migrate process instance", + id: "apis-tools/camunda-api-rest/specifications/query-incidents-alpha", + label: "Query incidents (alpha)", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/modify-process-instance", - label: "Modify process instance", - className: "api-method post", + id: "apis-tools/camunda-api-rest/specifications/get-incident-by-key-alpha", + label: "Get incident by key (alpha)", + className: "api-method get", }, ], }, { type: "category", - label: "Flow node Instance", + label: "Job", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-flow-node-instances-alpha", - label: "Query flow node instances (alpha)", + id: "apis-tools/camunda-api-rest/specifications/activate-jobs", + label: "Activate jobs", className: "api-method post", }, - ], - }, - { - type: "category", - label: "Decision definition", - items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-decision-definitions-alpha", - label: "Query decision definitions (alpha)", + id: "apis-tools/camunda-api-rest/specifications/fail-job", + label: "Fail job", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/get-decision-definition-xml-alpha", - label: "Get decision definition XML (alpha)", - className: "api-method get", + id: "apis-tools/camunda-api-rest/specifications/report-error-for-job", + label: "Report error for job", + className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/evaluate-decision", - label: "Evaluate decision", + id: "apis-tools/camunda-api-rest/specifications/complete-job", + label: "Complete job", className: "api-method post", }, - ], - }, - { - type: "category", - label: "Decision requirements", - items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-decision-requirements-alpha", - label: "Query decision requirements (alpha)", - className: "api-method post", + id: "apis-tools/camunda-api-rest/specifications/update-a-job", + label: "Update a job", + className: "api-method patch", }, ], }, { type: "category", - label: "Decision instance", + label: "License", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/query-decision-instances-alpha", - label: "Query decision instances (alpha)", - className: "api-method post", + id: "apis-tools/camunda-api-rest/specifications/get-status-of-camunda-license", + label: "Get status of Camunda license", + className: "api-method get", }, ], }, @@ -257,42 +227,36 @@ module.exports = [ }, { type: "category", - label: "Documents", + label: "Process instance", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/upload-document-alpha", - label: "Upload document (alpha)", + id: "apis-tools/camunda-api-rest/specifications/create-process-instance", + label: "Create process instance", className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/download-document-alpha", - label: "Download document (alpha)", - className: "api-method get", + id: "apis-tools/camunda-api-rest/specifications/query-process-instances-alpha", + label: "Query process instances (alpha)", + className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/delete-document-alpha", - label: "Delete document (alpha)", - className: "api-method delete", + id: "apis-tools/camunda-api-rest/specifications/cancel-process-instance", + label: "Cancel process instance", + className: "api-method post", }, { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/create-document-link-alpha", - label: "Create document link (alpha)", + id: "apis-tools/camunda-api-rest/specifications/migrate-process-instance", + label: "Migrate process instance", className: "api-method post", }, - ], - }, - { - type: "category", - label: "User", - items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/find-all-users", - label: "Query users (alpha)", + id: "apis-tools/camunda-api-rest/specifications/modify-process-instance", + label: "Modify process instance", className: "api-method post", }, ], @@ -317,24 +281,60 @@ module.exports = [ }, { type: "category", - label: "Element instance", + label: "Signal", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/update-element-instance-variables", - label: "Update element instance variables", + id: "apis-tools/camunda-api-rest/specifications/broadcast-signal", + label: "Broadcast signal", className: "api-method post", }, ], }, { type: "category", - label: "Signal", + label: "User", items: [ { type: "doc", - id: "apis-tools/camunda-api-rest/specifications/broadcast-signal", - label: "Broadcast signal", + id: "apis-tools/camunda-api-rest/specifications/find-all-users", + label: "Query users (alpha)", + className: "api-method post", + }, + ], + }, + { + type: "category", + label: "User task", + items: [ + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/complete-user-task", + label: "Complete user task", + className: "api-method post", + }, + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/assign-user-task", + label: "Assign user task", + className: "api-method post", + }, + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/update-user-task", + label: "Update user task", + className: "api-method patch", + }, + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/unassign-user-task", + label: "Unassign user task", + className: "api-method delete", + }, + { + type: "doc", + id: "apis-tools/camunda-api-rest/specifications/query-user-tasks-alpha", + label: "Query user tasks (alpha)", className: "api-method post", }, ], From 28c8885fc7d592fe1f36af646698589a3ff741cc Mon Sep 17 00:00:00 2001 From: Tobias Metzke-Bernstein <586643+tmetzke@users.noreply.github.com> Date: Thu, 7 Nov 2024 15:03:10 +0100 Subject: [PATCH 4/8] docs: adjust 8.6 sidebar for C8 REST API --- versioned_sidebars/version-8.6-sidebars.json | 277 ++++++++++--------- 1 file changed, 139 insertions(+), 138 deletions(-) diff --git a/versioned_sidebars/version-8.6-sidebars.json b/versioned_sidebars/version-8.6-sidebars.json index 11ae4143419..247c91bdd78 100644 --- a/versioned_sidebars/version-8.6-sidebars.json +++ b/versioned_sidebars/version-8.6-sidebars.json @@ -887,6 +887,7 @@ { "Camunda 8 API (REST)": [ "apis-tools/camunda-api-rest/camunda-api-rest-overview", + "apis-tools/camunda-api-rest/camunda-api-rest-guidelines", "apis-tools/camunda-api-rest/camunda-api-rest-authentication", { "Specifications": [ @@ -896,235 +897,205 @@ }, { "type": "category", - "label": "Cluster", + "label": "Clock", "items": [ { "type": "doc", - "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", + "label": "Pin internal clock (alpha)", + "className": "api-method put" + }, + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/reset-internal-clock-alpha", + "label": "Reset internal clock (alpha)", + "className": "api-method post" } ] }, { "type": "category", - "label": "License", + "label": "Cluster", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/get-status-of-camunda-license", - "label": "Get status of Camunda license", + "id": "apis-tools/camunda-api-rest/specifications/get-cluster-topology", + "label": "Get cluster topology", "className": "api-method get" } ] }, { "type": "category", - "label": "Job", + "label": "Decision definition", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/activate-jobs", - "label": "Activate jobs", - "className": "api-method post" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/fail-job", - "label": "Fail job", + "id": "apis-tools/camunda-api-rest/specifications/query-decision-definitions-alpha", + "label": "Query decision definitions (alpha)", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/report-error-for-job", - "label": "Report error for job", - "className": "api-method post" + "id": "apis-tools/camunda-api-rest/specifications/get-decision-definition-xml-alpha", + "label": "Get decision definition XML (alpha)", + "className": "api-method get" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/complete-job", - "label": "Complete job", + "id": "apis-tools/camunda-api-rest/specifications/evaluate-decision", + "label": "Evaluate decision", "className": "api-method post" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/update-a-job", - "label": "Update a job", - "className": "api-method patch" } ] }, { "type": "category", - "label": "Incident", + "label": "Decision instance", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/resolve-incident", - "label": "Resolve incident", - "className": "api-method post" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-incidents-alpha", - "label": "Query incidents (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/query-decision-instances-alpha", + "label": "Query decision instances (alpha)", "className": "api-method post" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/get-incident-by-key-alpha", - "label": "Get incident by key (alpha)", - "className": "api-method get" } ] }, { "type": "category", - "label": "User task", + "label": "Decision requirements", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/complete-user-task", - "label": "Complete user task", + "id": "apis-tools/camunda-api-rest/specifications/query-decision-requirements-alpha", + "label": "Query decision requirements (alpha)", "className": "api-method post" - }, + } + ] + }, + { + "type": "category", + "label": "Documents", + "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/assign-user-task", - "label": "Assign user task", + "id": "apis-tools/camunda-api-rest/specifications/upload-document-alpha", + "label": "Upload document (alpha)", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/update-user-task", - "label": "Update user task", - "className": "api-method patch" + "id": "apis-tools/camunda-api-rest/specifications/download-document-alpha", + "label": "Download document (alpha)", + "className": "api-method get" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/unassign-user-task", - "label": "Unassign user task", + "id": "apis-tools/camunda-api-rest/specifications/delete-document-alpha", + "label": "Delete document (alpha)", "className": "api-method delete" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-user-tasks-alpha", - "label": "Query user tasks (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/create-document-link-alpha", + "label": "Create document link (alpha)", "className": "api-method post" } ] }, { "type": "category", - "label": "Clock", + "label": "Element instance", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/pin-internal-clock-alpha", - "label": "Pin internal clock (alpha)", - "className": "api-method put" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/reset-internal-clock-alpha", - "label": "Reset internal clock (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/update-element-instance-variables", + "label": "Update element instance variables", "className": "api-method post" } ] }, { "type": "category", - "label": "Process instance", + "label": "Flow node Instance", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/create-process-instance", - "label": "Create process instance", - "className": "api-method post" - }, - { - "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-process-instances-alpha", - "label": "Query process instances (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/query-flow-node-instances-alpha", + "label": "Query flow node instances (alpha)", "className": "api-method post" - }, + } + ] + }, + { + "type": "category", + "label": "Incident", + "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/cancel-process-instance", - "label": "Cancel process instance", + "id": "apis-tools/camunda-api-rest/specifications/resolve-incident", + "label": "Resolve incident", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/migrate-process-instance", - "label": "Migrate process instance", + "id": "apis-tools/camunda-api-rest/specifications/query-incidents-alpha", + "label": "Query incidents (alpha)", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/modify-process-instance", - "label": "Modify process instance", - "className": "api-method post" + "id": "apis-tools/camunda-api-rest/specifications/get-incident-by-key-alpha", + "label": "Get incident by key (alpha)", + "className": "api-method get" } ] }, { "type": "category", - "label": "Flow node Instance", + "label": "Job", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-flow-node-instances-alpha", - "label": "Query flow node instances (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/activate-jobs", + "label": "Activate jobs", "className": "api-method post" - } - ] - }, - { - "type": "category", - "label": "Decision definition", - "items": [ + }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-decision-definitions-alpha", - "label": "Query decision definitions (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/fail-job", + "label": "Fail job", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/get-decision-definition-xml-alpha", - "label": "Get decision definition XML (alpha)", - "className": "api-method get" + "id": "apis-tools/camunda-api-rest/specifications/report-error-for-job", + "label": "Report error for job", + "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/evaluate-decision", - "label": "Evaluate decision", + "id": "apis-tools/camunda-api-rest/specifications/complete-job", + "label": "Complete job", "className": "api-method post" - } - ] - }, - { - "type": "category", - "label": "Decision requirements", - "items": [ + }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-decision-requirements-alpha", - "label": "Query decision requirements (alpha)", - "className": "api-method post" + "id": "apis-tools/camunda-api-rest/specifications/update-a-job", + "label": "Update a job", + "className": "api-method patch" } ] }, { "type": "category", - "label": "Decision instance", + "label": "License", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/query-decision-instances-alpha", - "label": "Query decision instances (alpha)", - "className": "api-method post" + "id": "apis-tools/camunda-api-rest/specifications/get-status-of-camunda-license", + "label": "Get status of Camunda license", + "className": "api-method get" } ] }, @@ -1148,42 +1119,36 @@ }, { "type": "category", - "label": "Documents", + "label": "Process instance", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/upload-document-alpha", - "label": "Upload document (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/create-process-instance", + "label": "Create process instance", "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/download-document-alpha", - "label": "Download document (alpha)", - "className": "api-method get" + "id": "apis-tools/camunda-api-rest/specifications/query-process-instances-alpha", + "label": "Query process instances (alpha)", + "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/delete-document-alpha", - "label": "Delete document (alpha)", - "className": "api-method delete" + "id": "apis-tools/camunda-api-rest/specifications/cancel-process-instance", + "label": "Cancel process instance", + "className": "api-method post" }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/create-document-link-alpha", - "label": "Create document link (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/migrate-process-instance", + "label": "Migrate process instance", "className": "api-method post" - } - ] - }, - { - "type": "category", - "label": "User", - "items": [ + }, { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/find-all-users", - "label": "Query users (alpha)", + "id": "apis-tools/camunda-api-rest/specifications/modify-process-instance", + "label": "Modify process instance", "className": "api-method post" } ] @@ -1208,24 +1173,60 @@ }, { "type": "category", - "label": "Element instance", + "label": "Signal", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/update-element-instance-variables", - "label": "Update element instance variables", + "id": "apis-tools/camunda-api-rest/specifications/broadcast-signal", + "label": "Broadcast signal", "className": "api-method post" } ] }, { "type": "category", - "label": "Signal", + "label": "User", "items": [ { "type": "doc", - "id": "apis-tools/camunda-api-rest/specifications/broadcast-signal", - "label": "Broadcast signal", + "id": "apis-tools/camunda-api-rest/specifications/find-all-users", + "label": "Query users (alpha)", + "className": "api-method post" + } + ] + }, + { + "type": "category", + "label": "User task", + "items": [ + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/complete-user-task", + "label": "Complete user task", + "className": "api-method post" + }, + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/assign-user-task", + "label": "Assign user task", + "className": "api-method post" + }, + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/update-user-task", + "label": "Update user task", + "className": "api-method patch" + }, + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/unassign-user-task", + "label": "Unassign user task", + "className": "api-method delete" + }, + { + "type": "doc", + "id": "apis-tools/camunda-api-rest/specifications/query-user-tasks-alpha", + "label": "Query user tasks (alpha)", "className": "api-method post" } ] From e0b223a97180903c178cab19b0e03b0f3db049cf Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Tue, 12 Nov 2024 16:17:39 -0500 Subject: [PATCH 5/8] style(formatting): grammatical tweaks --- .../camunda-api-rest-guidelines.md | 44 +++++++++---------- .../camunda-api-rest-guidelines.md | 40 ++++++++--------- 2 files changed, 40 insertions(+), 44 deletions(-) diff --git a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index fdbc0027ba7..8cba286ca21 100644 --- a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -1,12 +1,10 @@ --- id: camunda-api-rest-guidelines title: "Guidelines" -description: "Learn about the basic guidelines , structures, and conventions of the Camunda 8 REST API." +description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- -# API guidelines - -As outlined below in this document, we follow a mix of proposed standards and best practices for RESTful design and implementation consistently across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. +Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. ## Naming conventions @@ -14,16 +12,16 @@ Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This i The API overall applies the following naming conventions: -- We favor **nouns** over verbs, e.g. _assignment_ over _assign_. -- For top-level resources, we use plural terms, e.g. _user-tasks_. -- In path parameters, we use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, e.g. _user-tasks_. -- In query parameters, we use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, e.g. _userTaskKey_. +- **Nouns** over verbs, for example, _assignment_ over _assign_. +- For top-level resources, use plural terms, for example, _user-tasks_. +- In path parameters, use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, for example, _user-tasks_. +- In query parameters, use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, for example, _userTaskKey_. -All of this can be observed in the following endpoint example: +These conventions can be observed in the following endpoint example: > POST /user-tasks/{userTaskKey}/**assignment** -When working with IDs or similar short two or three-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. +When working with IDs or similar short 2- or 3-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. | term | usage | | ---- | ------------------------------------------ | @@ -33,24 +31,24 @@ When working with IDs or similar short two or three-letter words or acronyms, do Identifiers follow a naming rule, in parameters and data attributes alike: -- Unique technical identifiers are suffixed with **key**, e.g. _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. -- Other identifiers, e.g. copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, e.g. _processDefinitionId_. +- Unique technical identifiers are suffixed with **key**, for example, _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. +- Other identifiers, such as copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, for example, _processDefinitionId_. ## Versioning -We use the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, we provide updates to the API in place and only increment the version number when a major, breaking change happens. +Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increment the version number when a major, breaking change happens. Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. -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”. +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, for example, “_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”. +Camunda does API versioning rather than endpoint versioning, for example, 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, for example, “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”. ## HTTP status codes & error handling -Handling errors has to be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. +Handling errors must be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. -We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: +Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: - Type - Status @@ -58,7 +56,7 @@ We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/r - Detail - Instance -We use the following error codes and descriptions across our APIs: +Camunda uses the following error codes and descriptions across our APIs: - 200 OK - 204 No Content @@ -75,7 +73,7 @@ We use the following error codes and descriptions across our APIs: - 412 Precondition failed - The client should check the cluster status. - 429 Rate Limited Exceeded - - The client exceeds a defined limit of requests, e.g. Zeebe signaling backpressure due to more requests than the broker can currently process + - The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process - 500 Internal Server Error - Generic error that contains further description in the problem detail. @@ -83,7 +81,7 @@ Each error code should have clear guidance in the documentation and API referenc ## 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. +Most resources provide at least one endpoint to fetch related data. Most of those endpoints provide data with near-real time consistency queried from exported records, if records for the respective resource are exported by the engine. If resources are not based on exported records, for example license data or topology information, the data returned by those endpoints can reflect real time insights or static content. For most resources, there are search endpoints to query by POST method and a given query request object where applicable. The structure of such query requests always follows the same schema and so does the response, always returning a list of items matching the query criteria. @@ -120,11 +118,11 @@ The **page** object details how to slice the result set. An initial search reque } ``` -#### Advanced Search +#### Advanced search To provide an easy yet expressive way for users to search for and filter resources, search requests can contain more advanced filter criteria than fields being _equal_ to a target value. -For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of supported advanced filter operators is described below. Examples of advanced operators are shown in the [Search example](#search-example). +For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of supported advanced filter operators is described below. Examples of advanced operators are shown in the [search example](#search-example). ##### Conditional operators @@ -298,7 +296,7 @@ POST /v2/user-tasks/search } ``` -This yields the next 3 user task items after the last one from the first search request’s result. +This yields the next three user task items after the last one from the first search request’s result. ## Date values diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index fc07699134e..9db4943e791 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -1,12 +1,10 @@ --- id: camunda-api-rest-guidelines title: "Guidelines" -description: "Learn about the basic guidelines , structures, and conventions of the Camunda 8 REST API." +description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- -# API guidelines - -As outlined below in this document, we follow a mix of proposed standards and best practices for RESTful design and implementation consistently across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. +Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. ## Naming conventions @@ -14,16 +12,16 @@ Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This i The API overall applies the following naming conventions: -- We favor **nouns** over verbs, e.g. _assignment_ over _assign_. -- For top-level resources, we use plural terms, e.g. _user-tasks_. -- In path parameters, we use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, e.g. _user-tasks_. -- In query parameters, we use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, e.g. _userTaskKey_. +- **Nouns** over verbs, for example, _assignment_ over _assign_. +- For top-level resources, use plural terms, for example, _user-tasks_. +- In path parameters, use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, for example, _user-tasks_. +- In query parameters, use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, for example, _userTaskKey_. -All of this can be observed in the following endpoint example: +These conventions can be observed in the following endpoint example: > POST /user-tasks/{userTaskKey}/**assignment** -When working with IDs or similar short two or three-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. +When working with IDs or similar short 2- or 3-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. | term | usage | | ---- | ------------------------------------------ | @@ -33,24 +31,24 @@ When working with IDs or similar short two or three-letter words or acronyms, do Identifiers follow a naming rule, in parameters and data attributes alike: -- Unique technical identifiers are suffixed with **key**, e.g. _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. -- Other identifiers, e.g. copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, e.g. _processDefinitionId_. +- Unique technical identifiers are suffixed with **key**, for example, _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. +- Other identifiers, such as copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, for example, _processDefinitionId_. ## Versioning -We use the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, we provide updates to the API in place and only increment the version number when a major, breaking change happens. +Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increment the version number when a major, breaking change happens. Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. -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”. +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, for example, “_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”. +Camunda does API versioning rather than endpoint versioning, for example, 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, for example, “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”. ## HTTP status codes & error handling -Handling errors has to be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. +Handling errors must be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. -We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: +Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: - Type - Status @@ -58,7 +56,7 @@ We follow the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/r - Detail - Instance -We use the following error codes and descriptions across our APIs: +Camunda uses the following error codes and descriptions across our APIs: - 200 OK - 204 No Content @@ -75,7 +73,7 @@ We use the following error codes and descriptions across our APIs: - 412 Precondition failed - The client should check the cluster status. - 429 Rate Limited Exceeded - - The client exceeds a defined limit of requests, e.g. Zeebe signaling backpressure due to more requests than the broker can currently process + - The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process - 500 Internal Server Error - Generic error that contains further description in the problem detail. @@ -83,7 +81,7 @@ Each error code should have clear guidance in the documentation and API referenc ## 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. +Most resources provide at least one endpoint to fetch related data. Most of those endpoints provide data with near-real time consistency queried from exported records, if records for the respective resource are exported by the engine. If resources are not based on exported records, for example license data or topology information, the data returned by those endpoints can reflect real time insights or static content. For most resources, there are search endpoints to query by POST method and a given query request object where applicable. The structure of such query requests always follows the same schema and so does the response, always returning a list of items matching the query criteria. @@ -233,7 +231,7 @@ POST /v2/user-tasks/search } ``` -This yields the next 3 user task items after the last one from the first search request’s result. +This yields the next three user task items after the last one from the first search request’s result. ## Date values From a915eb1a2ad77abb234213a22667eaa22e5b2798 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Mon, 9 Dec 2024 16:08:09 -0500 Subject: [PATCH 6/8] style(formatting): technical review --- .../camunda-api-rest-guidelines.md | 86 +++++++++---------- .../camunda-api-rest-guidelines.md | 56 ++++++------ 2 files changed, 71 insertions(+), 71 deletions(-) diff --git a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index 8cba286ca21..9fe08874660 100644 --- a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -4,49 +4,49 @@ title: "Guidelines" description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- -Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. +Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. ## Naming conventions -Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This improves the experience when working across multiple APIs by reducing friction. +Naming is simple, intuitive, and consistent across Camunda 8 APIs to reduce friction when working across multiple APIs. The API overall applies the following naming conventions: -- **Nouns** over verbs, for example, _assignment_ over _assign_. -- For top-level resources, use plural terms, for example, _user-tasks_. -- In path parameters, use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, for example, _user-tasks_. -- In query parameters, use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, for example, _userTaskKey_. +- **Nouns** over verbs, for example, `assignment` over `assign`. +- **Plural terms** for top-level resources, for example, `user-tasks`. +- **Kebab-case** for multiple words in path parameters, and a hyphen (-) where a space would exist, for example, `user-tasks`. +- **camelCase** for multiple words in query parameters. Camunda capitalizes the first letter of words after the first. The first letter in the first word is lowercase, for example, `userTaskKey`. These conventions can be observed in the following endpoint example: -> POST /user-tasks/{userTaskKey}/**assignment** +`POST /user-tasks/{userTaskKey}/**assignment**` -When working with IDs or similar short 2- or 3-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. +For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitalizes the first letter. If standalone, all letters are lowercase. -| term | usage | +| Term | Usage | | ---- | ------------------------------------------ | -| ID | _id_ (standalone) or _processDefinitionId_ | -| URL | _url_ (standalone) or _externalUrl_ | -| UUID | _uuid_ (standalone) or _clusterUuid_ | +| ID | `id` (standalone) or `processDefinitionId` | +| URL | `url` (standalone) or `externalUrl` | +| UUID | `uuid` (standalone) or `clusterUuid` | Identifiers follow a naming rule, in parameters and data attributes alike: -- Unique technical identifiers are suffixed with **key**, for example, _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. -- Other identifiers, such as copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, for example, _processDefinitionId_. +- Unique technical identifiers are suffixed with **key**, for example, `userTaskKey`, `processInstanceKey`, or `userKey`. These are numeric values in most cases. +- Other identifiers, such as copied identifiers from the BPMN XML, may be arbitrarily named but are usually suffixed with **id**, for example, `processDefinitionId`. ## Versioning -Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increment the version number when a major, breaking change happens. +Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but does not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increments the version number for a major, breaking change. Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. -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, for example, “_POST /v2/user-tasks/search_ in Camunda 8.7.0”. +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, for example, `_POST /v2/user-tasks/search_ in Camunda 8.7.0`. -Camunda does API versioning rather than endpoint versioning, for example, 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, for example, “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”. +Camunda does API versioning rather than endpoint versioning, for example, 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, for example, `POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0`. ## HTTP status codes & error handling -Handling errors must be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. +Handling errors is consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: @@ -77,7 +77,7 @@ Camunda uses the following error codes and descriptions across our APIs: - 500 Internal Server Error - Generic error that contains further description in the problem detail. -Each error code should have clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. +Each error code has clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. ## Data fetching @@ -87,9 +87,9 @@ For most resources, there are search endpoints to query by POST method and a giv [Search requests](#search-requests) are forwarded as queries to the datastores that hold the exported records and the query results are returned in the format described in [search responses](#search-responses). -Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at _POST /v2/users/search_, a user's groups can be retrieved using _POST /v2/users/{userKey}/groups/search_. Each resource determines independently if subordinate resources can be accessed this way. +Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at `POST /v2/users/search`, a user's groups can be retrieved using `POST /v2/users/{userKey}/groups/search`. Each resource determines independently if subordinate resources can be accessed this way. -Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, e.g. _GET /v2/users/{userKey}_. +Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, for example `GET /v2/users/{userKey}`. ### Search requests @@ -99,7 +99,7 @@ The **filter** object defines which fields should match. Only items that match t 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_. +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`. ``` { @@ -126,17 +126,17 @@ For example, this allows searching using logical (and, in) and comparison operat ##### Conditional operators -| Operator | Syntax | Description | -| -------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| $eq | field: { "$eq": value } | Filter where field is equal to value. Abbreviated form field: value is also allowed. | -| $neq | field: { "$neq": value } | Filter where field is not equal to value. | -| $exists | field: { "$exists": value } | Filter where field does or does not exist. The value is a boolean and can be either true or false. | -| $gt | field: { "$gt": value } | Filter where field is greater than value. Supports numeric and [Date values](#date-values). | -| $gte | field: { "$gte": value } | Filter where field is greater than or equal to value. Supports numeric and [Date values](#date-values). | -| $lt | field: { "$lt": value } | Filter where field is less than value. Supports numeric and [Date values](#date-values). | -| $lte | field: { "$lte": value } | Filter where field is less than or equal to value. Supports numeric and [Date values](#date-values). | -| $like | field: { "$like": value } | Filter where field contains a string like value. Use \* as a placeholder for an arbitrary number of characters anywhere in value. Supports string values. | -| $in | field: { "$in": [ value1, value2, ... ] } | Filter where field is equal to any of the values in the provided array. | +| Operator | Syntax | Description | +| -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| $eq | field: { "$eq": value } | Filter where field is equal to value. Abbreviated form field: value is also allowed. | +| $neq | field: { "$neq": value } | Filter where field is not equal to value. | +| $exists | field: { "$exists": value } | Filter where field does or does not exist. The value is a boolean and can be either true or false. | +| $gt | field: { "$gt": value } | Filter where field is greater than value. Supports numeric and [Date values](#date-values). | +| $gte | field: { "$gte": value } | Filter where field is greater than or equal to value. Supports numeric and [Date values](#date-values). | +| $lt | field: { "$lt": value } | Filter where field is less than value. Supports numeric and [Date values](#date-values). | +| $lte | field: { "$lte": value } | Filter where field is less than or equal to value. Supports numeric and [Date values](#date-values). | +| $like | field: { "$like": value } | Filter where field contains a string like value. \* is used as a placeholder for an arbitrary number of characters anywhere in value. Supports string values. | +| $in | field: { "$in": [ value1, value2, ... ] } | Filter where field is equal to any of the values in the provided array. | ##### Logical operators @@ -147,9 +147,9 @@ For example, this allows searching using logical (and, in) and comparison operat ##### Variable filtering -Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the _variables_ object and defining filter criteria for specific variables in there. +Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the _variables_ object and defining filter criteria for specific variables. -In general, the syntax looks as follows: +Generally, the syntax looks as follows: ``` POST /v2/user-tasks/search @@ -165,9 +165,9 @@ POST /v2/user-tasks/search } ``` -This filters for user tasks containing at least the variables _orderVolume_ with a value of _10000_ and _foo_ with a value lower than _500_, and **not** containing variable _bar_. +This filters for user tasks containing at least the variables `orderVolume` with a value of `10000` and `foo` with a value lower than `500`, and **not** containing variable `bar`. -For variable values, the filter criteria outlined above for fields can be used. +For variable values, the filter criteria outlined above for fields may be used. ### Search responses @@ -175,9 +175,9 @@ Query responses consist of the components **items** and **page**. The **items** object is an array of instances of the respective endpoint’s resource. The attributes of those instances vary by endpoint and are described in the endpoint’s documentation. -The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The _totalItems_ attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). +The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The `totalItems` attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). -The _firstSortValues_ field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like _searchBefore_ in a [search request](#search-requests). The _lastSortValues_ field provides the same for the **last** entry of this page to allow paging forward using _searchAfter_. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s _sort_ object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute: usually that is the internal record’s key. +The `firstSortValues` field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like `searchBefore` in a [search request](#search-requests). The `lastSortValues` field provides the same for the **last** entry of this page to allow paging forward using `searchAfter`. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s `sort` object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute, typically the internal record’s key. ``` { @@ -205,7 +205,7 @@ The _firstSortValues_ field lists the criteria identifying the **first** entry o ### Search example -Querying for the first 3 user tasks with certain criteria, sorted by state, could look as follows: +Querying for the first three user tasks with certain criteria sorted by state could look as follows: ``` POST /v2/user-tasks/search @@ -267,7 +267,7 @@ This could yield the following example result: } ``` -A follow-up request to receive the next 3 items could then look as follows: +A follow-up request to receive the next three items could then look as follows: ``` POST /v2/user-tasks/search @@ -300,8 +300,8 @@ This yields the next three user task items after the last one from the first sea ## Date values -All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. +All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints must validate requests and transform responses accordingly. ## Variables -Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. +Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints must validate requests and transform responses accordingly. diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index 9db4943e791..c25f7c68494 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -4,49 +4,49 @@ title: "Guidelines" description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- -Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. This ensures customers working across all component APIs have a consistent and expected experience without having to study our API reference material or perform “validation testing” to see how our APIs respond. +Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. ## Naming conventions -Naming should be simple, intuitive, and consistent across Camunda 8 APIs. This improves the experience when working across multiple APIs by reducing friction. +Naming is simple, intuitive, and consistent across Camunda 8 APIs to reduce friction when working across multiple APIs. The API overall applies the following naming conventions: -- **Nouns** over verbs, for example, _assignment_ over _assign_. -- For top-level resources, use plural terms, for example, _user-tasks_. -- In path parameters, use **kebab-case** for multiple words. Use a hyphen (-) where a space would exist, for example, _user-tasks_. -- In query parameters, use **camelCase** for multiple words. Always capitalize the first letter of words after the first. The first letter in the first word must be lowercase, for example, _userTaskKey_. +- **Nouns** over verbs, for example, `assignment` over `assign`. +- **Plural terms** for top-level resources, for example, `user-tasks`. +- **Kebab-case** for multiple words in path parameters, and a hyphen (-) where a space would exist, for example, `user-tasks`. +- **camelCase** for multiple words in query parameters. Camunda capitalizes the first letter of words after the first. The first letter in the first word is lowercase, for example, `userTaskKey`. These conventions can be observed in the following endpoint example: -> POST /user-tasks/{userTaskKey}/**assignment** +`POST /user-tasks/{userTaskKey}/**assignment**` -When working with IDs or similar short 2- or 3-letter words or acronyms, don’t capitalize all letters, only capitalize the first letter. If standalone, all letters should be lowercase. +For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitalizes the first letter. If standalone, all letters are lowercase. -| term | usage | +| Term | Usage | | ---- | ------------------------------------------ | -| ID | _id_ (standalone) or _processDefinitionId_ | -| URL | _url_ (standalone) or _externalUrl_ | -| UUID | _uuid_ (standalone) or _clusterUuid_ | +| ID | `id` (standalone) or `processDefinitionId` | +| URL | `url` (standalone) or `externalUrl` | +| UUID | `uuid` (standalone) or `clusterUuid` | Identifiers follow a naming rule, in parameters and data attributes alike: -- Unique technical identifiers are suffixed with **key**, for example, _userTaskKey_, _processInstanceKey_, _userKey_. They are numeric values in most cases. -- Other identifiers, such as copied identifiers from the BPMN XML, can be arbitrarily named but are usually suffixed with **id**, for example, _processDefinitionId_. +- Unique technical identifiers are suffixed with **key**, for example, `userTaskKey`, `processInstanceKey`, or `userKey`. These are numeric values in most cases. +- Other identifiers, such as copied identifiers from the BPMN XML, may be arbitrarily named but are usually suffixed with **id**, for example, `processDefinitionId`. ## Versioning -Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but do not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increment the version number when a major, breaking change happens. +Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but does not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increments the version number for a major, breaking change. Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. -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, for example, “_POST /v2/user-tasks/search_ in Camunda 8.7.0”. +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, for example, `_POST /v2/user-tasks/search_ in Camunda 8.7.0`. -Camunda does API versioning rather than endpoint versioning, for example, 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, for example, “POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0”. +Camunda does API versioning rather than endpoint versioning, for example, 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, for example, `POST /v2/user-tasks/search and POST /v3/user-tasks/search in Camunda 8.7.0`. ## HTTP status codes & error handling -Handling errors must be consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. +Handling errors is consistent across all endpoints, using well-known HTTP status codes and clear descriptions. This includes the information about errors and the use of a problem details object. Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) for problem details. The problem object contains at least the following members: @@ -77,7 +77,7 @@ Camunda uses the following error codes and descriptions across our APIs: - 500 Internal Server Error - Generic error that contains further description in the problem detail. -Each error code should have clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. +Each error code has clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. ## Data fetching @@ -87,9 +87,9 @@ For most resources, there are search endpoints to query by POST method and a giv [Search requests](#search-requests) are forwarded as queries to the datastores that hold the exported records and the query results are returned in the format described in [search responses](#search-responses). -Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at _POST /v2/users/search_, a user's groups can be retrieved using _POST /v2/users/{userKey}/groups/search_. Each resource determines independently if subordinate resources can be accessed this way. +Resources can also support querying subordinate resources. For example, for users and groups, with user search being available at `POST /v2/users/search`, a user's groups can be retrieved using `POST /v2/users/{userKey}/groups/search`. Each resource determines independently if subordinate resources can be accessed this way. -Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, e.g. _GET /v2/users/{userKey}_. +Search endpoints can also be used to directly access entity instances with a unique identifier. As an alternative, resources can also provide GET method endpoints for fetching the data of single instances. In most cases, this is done by a specific key parameter in the URL path, for example `GET /v2/users/{userKey}`. ### Search requests @@ -99,7 +99,7 @@ The **filter** object defines which fields should match. Only items that match t 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_. +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`. ``` { @@ -124,9 +124,9 @@ Query responses consist of the components **items** and **page**. The **items** object is an array of instances of the respective endpoint’s resource. The attributes of those instances vary by endpoint and are described in the endpoint’s documentation. -The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The _totalItems_ attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). +The **page** object contains the pagination information that can be used for subsequent search requests to page through the results. The `totalItems` attribute specifies the overall number of results for the query to be retrieved (note: for ES/OS, this is limited to 10,000, even if more results are available). -The _firstSortValues_ field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like _searchBefore_ in a [search request](#search-requests). The _lastSortValues_ field provides the same for the **last** entry of this page to allow paging forward using _searchAfter_. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s _sort_ object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute: usually that is the internal record’s key. +The `firstSortValues` field lists the criteria identifying the **first** entry of this page to allow paging backward in the result set by copying them into a respective page attribute like `searchBefore` in a [search request](#search-requests). The `lastSortValues` field provides the same for the **last** entry of this page to allow paging forward using `searchAfter`. In detail, those arrays contain the values of the first or last item’s attributes corresponding to the attributes defined in the request’s `sort` object, in the same order. The last element of the array is the item’s value of our internal tiebreaker attribute, typically the internal record’s key. ``` { @@ -154,7 +154,7 @@ The _firstSortValues_ field lists the criteria identifying the **first** entry o ### Search example -Querying for the first 3 user tasks with certain criteria, sorted by state, could look as follows: +Querying for the first three user tasks with certain criteria sorted by state could look as follows: ``` POST /v2/user-tasks/search @@ -209,7 +209,7 @@ This could yield the following example result: } ``` -A follow-up request to receive the next 3 items could then look as follows: +A follow-up request to receive the next three items could then look as follows: ``` POST /v2/user-tasks/search @@ -235,8 +235,8 @@ This yields the next three user task items after the last one from the first sea ## Date values -All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. +All date values in the REST API endpoints follow the [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) notation. This includes all requests and responses. Endpoints must validate requests and transform responses accordingly. ## Variables -Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints need to validate requests and transform responses accordingly. +Variables in the REST API endpoints are proper JSON objects, where the key defines the variable name and the value specifies the variable value. This includes all requests and responses. Endpoints must validate requests and transform responses accordingly. From 2c700a0bafbb84b7564768b5e39398523641f874 Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Tue, 10 Dec 2024 13:35:25 -0500 Subject: [PATCH 7/8] format --- .../camunda-api-rest-guidelines.md | 109 +++++++++++------- .../camunda-api-rest-guidelines.md | 93 +++++++++------ 2 files changed, 129 insertions(+), 73 deletions(-) diff --git a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index 9fe08874660..c4d6be97ce6 100644 --- a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -4,6 +4,9 @@ title: "Guidelines" description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. ## Naming conventions @@ -19,7 +22,7 @@ The API overall applies the following naming conventions: These conventions can be observed in the following endpoint example: -`POST /user-tasks/{userTaskKey}/**assignment**` +`POST /user-tasks/{userTaskKey}/assignment` For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitalizes the first letter. If standalone, all letters are lowercase. @@ -29,7 +32,7 @@ For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitali | URL | `url` (standalone) or `externalUrl` | | UUID | `uuid` (standalone) or `clusterUuid` | -Identifiers follow a naming rule, in parameters and data attributes alike: +Identifiers follow a naming rule in parameters and data attributes alike: - Unique technical identifiers are suffixed with **key**, for example, `userTaskKey`, `processInstanceKey`, or `userKey`. These are numeric values in most cases. - Other identifiers, such as copied identifiers from the BPMN XML, may be arbitrarily named but are usually suffixed with **id**, for example, `processDefinitionId`. @@ -38,7 +41,9 @@ Identifiers follow a naming rule, in parameters and data attributes alike: Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but does not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increments the version number for a major, breaking change. -Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. +:::note +New attributes and endpoints are not considered breaking changes. +::: 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, for example, `_POST /v2/user-tasks/search_ in Camunda 8.7.0`. @@ -58,26 +63,18 @@ Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org Camunda uses the following error codes and descriptions across our APIs: -- 200 OK -- 204 No Content -- 400 Bad Request - - Generic error that contains further description in the problem detail. -- 401 Unauthorized - - The client is not authenticated yet. - - The client should try again with a modified Authorization header. -- 403 Forbidden - - The client has incorrect or insufficient permissions for the request. -- 404 Not Found -- 409 Conflict - - The request is trying to modify a resource that is currently not in the right state. -- 412 Precondition failed - - The client should check the cluster status. -- 429 Rate Limited Exceeded - - The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process -- 500 Internal Server Error - - Generic error that contains further description in the problem detail. - -Each error code has clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. +| Error code | Meaning | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | +| 204 | No content | +| 400 | Bad request. Generic error that contains further description in the problem detail. | +| 401 | Unauthorized. The client is not authenticated yet. The client should try again with a modified authorization header. | +| 403 | Forbidden. The client has incorrect or insufficient permissions for the request. | +| 404 | Not found | +| 409 | Conflict. The request is trying to modify a resource that is currently not in the right state. | +| 412 | Precondition failed. The client should check the cluster status. | +| 429 | Rate limit exceeded. The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process. | +| 500 | Internal server error. Generic error that contains further description in the problem detail. | ## Data fetching @@ -95,11 +92,21 @@ Search endpoints can also be used to directly access entity instances with a uni Query requests consist of the components for **filter**, **sort**, and **page**. -The **filter** object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. - -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`. + + +The filter object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. + + +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. + + + +
+

Example

 +

``` { @@ -118,13 +125,17 @@ The **page** object details how to slice the result set. An initial search reque } ``` +

+
+ #### Advanced search To provide an easy yet expressive way for users to search for and filter resources, search requests can contain more advanced filter criteria than fields being _equal_ to a target value. For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of supported advanced filter operators is described below. Examples of advanced operators are shown in the [search example](#search-example). -##### Conditional operators + + | Operator | Syntax | Description | | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -138,16 +149,18 @@ For example, this allows searching using logical (and, in) and comparison operat | $like | field: { "$like": value } | Filter where field contains a string like value. \* is used as a placeholder for an arbitrary number of characters anywhere in value. Supports string values. | | $in | field: { "$in": [ value1, value2, ... ] } | Filter where field is equal to any of the values in the provided array. | -##### Logical operators + + | Operator | Syntax | Description | | -------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | $or | "$or": [ { condition1 }, { condition2 }, ... ] | Filter where at least one of the conditions is true. | | and | { field: { "$lt": value1 }, field: { "$gt": value2 }, ... } | All conditions outside of $or operators will be considered as combined by an and operator. There is no explicit operator. | -##### Variable filtering + + -Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the _variables_ object and defining filter criteria for specific variables. +Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the variables object and defining filter criteria for specific variables. Generally, the syntax looks as follows: @@ -165,10 +178,13 @@ POST /v2/user-tasks/search } ``` -This filters for user tasks containing at least the variables `orderVolume` with a value of `10000` and `foo` with a value lower than `500`, and **not** containing variable `bar`. +This filters for user tasks containing at least the variables orderVolume with a value of 10000 and foo with a value lower than 500, and not containing variable bar. For variable values, the filter criteria outlined above for fields may be used. + + + ### Search responses Query responses consist of the components **items** and **page**. @@ -207,9 +223,11 @@ The `firstSortValues` field lists the criteria identifying the **first** entry o Querying for the first three user tasks with certain criteria sorted by state could look as follows: -``` -POST /v2/user-tasks/search +
+

POST /v2/user-tasks/search

 +

+``` { "filter": { "assignee": {"$eq": "demo"}, @@ -233,11 +251,16 @@ POST /v2/user-tasks/search } ``` +

+
+ This could yield the following example result: -``` -200 OK +
+

200 OK

 +

+``` { "items": [ { @@ -267,11 +290,16 @@ This could yield the following example result: } ``` +

+
+ A follow-up request to receive the next three items could then look as follows: -``` -POST /v2/user-tasks/search +
+

POST /v2/user-tasks/search

 +

+``` { "filter": { "assignee": {"$eq": "demo"}, @@ -296,6 +324,9 @@ POST /v2/user-tasks/search } ``` +

+
+ This yields the next three user task items after the last one from the first search request’s result. ## Date values diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index c25f7c68494..cf09f60f155 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -4,6 +4,9 @@ title: "Guidelines" description: "Learn about the basic guidelines, structures, and conventions of the Camunda 8 REST API." --- +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + Camunda follows a mix of proposed standards and best practices for RESTful design and consistent implementation across all components. ## Naming conventions @@ -19,7 +22,7 @@ The API overall applies the following naming conventions: These conventions can be observed in the following endpoint example: -`POST /user-tasks/{userTaskKey}/**assignment**` +`POST /user-tasks/{userTaskKey}/assignment` For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitalizes the first letter. If standalone, all letters are lowercase. @@ -29,7 +32,7 @@ For IDs or similar short 2- or 3-letter words or acronyms, Camunda only capitali | URL | `url` (standalone) or `externalUrl` | | UUID | `uuid` (standalone) or `clusterUuid` | -Identifiers follow a naming rule, in parameters and data attributes alike: +Identifiers follow a naming rule in parameters and data attributes alike: - Unique technical identifiers are suffixed with **key**, for example, `userTaskKey`, `processInstanceKey`, or `userKey`. These are numeric values in most cases. - Other identifiers, such as copied identifiers from the BPMN XML, may be arbitrarily named but are usually suffixed with **id**, for example, `processDefinitionId`. @@ -38,7 +41,9 @@ Identifiers follow a naming rule, in parameters and data attributes alike: Camunda uses the term “major version number” from [semantic versioning](https://semver.org/), but does not follow semantic versioning for APIs outright. Instead, Camunda provides updates to the API in place and only increments the version number for a major, breaking change. -Adding attributes and endpoints are not considered breaking changes. Breaking changes can potentially break an integration. See [GitHub’s REST documentation](https://docs.github.com/en/rest/about-the-rest-api/breaking-changes?apiVersion=2022-11-28#about-breaking-changes-in-the-rest-api) for a comprehensive summary of breaking changes. No migration is required unless there is a breaking change. +:::note +New attributes and endpoints are not considered breaking changes. +::: 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, for example, `_POST /v2/user-tasks/search_ in Camunda 8.7.0`. @@ -58,26 +63,18 @@ Camunda follows the proposed standard from [RFC 9457](https://www.rfc-editor.org Camunda uses the following error codes and descriptions across our APIs: -- 200 OK -- 204 No Content -- 400 Bad Request - - Generic error that contains further description in the problem detail. -- 401 Unauthorized - - The client is not authenticated yet. - - The client should try again with a modified Authorization header. -- 403 Forbidden - - The client has incorrect or insufficient permissions for the request. -- 404 Not Found -- 409 Conflict - - The request is trying to modify a resource that is currently not in the right state. -- 412 Precondition failed - - The client should check the cluster status. -- 429 Rate Limited Exceeded - - The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process -- 500 Internal Server Error - - Generic error that contains further description in the problem detail. - -Each error code has clear guidance in the documentation and API reference for how they should be handled. The problem detail object can provide guidance as well. +| Error code | Meaning | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 | OK | +| 204 | No content | +| 400 | Bad request. Generic error that contains further description in the problem detail. | +| 401 | Unauthorized. The client is not authenticated yet. The client should try again with a modified authorization header. | +| 403 | Forbidden. The client has incorrect or insufficient permissions for the request. | +| 404 | Not found | +| 409 | Conflict. The request is trying to modify a resource that is currently not in the right state. | +| 412 | Precondition failed. The client should check the cluster status. | +| 429 | Rate limit exceeded. The client exceeds a defined limit of requests, for example, Zeebe signaling backpressure due to more requests than the broker can currently process. | +| 500 | Internal server error. Generic error that contains further description in the problem detail. | ## Data fetching @@ -95,11 +92,21 @@ Search endpoints can also be used to directly access entity instances with a uni Query requests consist of the components for **filter**, **sort**, and **page**. -The **filter** object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. - -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`. + + +The filter object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. + + +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. + + + +
+

Example

 +

``` { @@ -118,6 +125,9 @@ The **page** object details how to slice the result set. An initial search reque } ``` +

+
+ ### Search responses Query responses consist of the components **items** and **page**. @@ -156,9 +166,11 @@ The `firstSortValues` field lists the criteria identifying the **first** entry o Querying for the first three user tasks with certain criteria sorted by state could look as follows: -``` -POST /v2/user-tasks/search +
+

POST /v2/user-tasks/search

 +

+``` { "filter": { "assignee": "demo", @@ -175,11 +187,16 @@ POST /v2/user-tasks/search } ``` +

+
+ This could yield the following example result: -``` -200 OK +
+

200 OK

 +

+``` { "items": [ { @@ -209,11 +226,16 @@ This could yield the following example result: } ``` +

+
+ A follow-up request to receive the next three items could then look as follows: -``` -POST /v2/user-tasks/search +
+

POST /v2/user-tasks/search

 +

+``` { "filter": { "assignee": "demo", @@ -231,6 +253,9 @@ POST /v2/user-tasks/search } ``` +

+
+ This yields the next three user task items after the last one from the first search request’s result. ## Date values From e46326156e54301ead0943a9e9be14eac745ed1d Mon Sep 17 00:00:00 2001 From: Christina Ausley Date: Tue, 10 Dec 2024 14:55:08 -0500 Subject: [PATCH 8/8] add spacing for easier reading --- .../camunda-api-rest/camunda-api-rest-guidelines.md | 12 ++++++++++++ .../camunda-api-rest/camunda-api-rest-guidelines.md | 2 ++ 2 files changed, 14 insertions(+) diff --git a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index c4d6be97ce6..9f494305dd7 100644 --- a/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -93,14 +93,23 @@ Search endpoints can also be used to directly access entity instances with a uni Query requests consist of the components for **filter**, **sort**, and **page**. + + The filter object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes. + + + 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. + @@ -135,6 +144,7 @@ To provide an easy yet expressive way for users to search for and filter resourc For example, this allows searching using logical (and, in) and comparison operators (greater than, less than). The list of supported advanced filter operators is described below. Examples of advanced operators are shown in the [search example](#search-example). + | Operator | Syntax | Description | @@ -150,6 +160,7 @@ For example, this allows searching using logical (and, in) and comparison operat | $in | field: { "$in": [ value1, value2, ... ] } | Filter where field is equal to any of the values in the provided array. | + | Operator | Syntax | Description | @@ -158,6 +169,7 @@ For example, this allows searching using logical (and, in) and comparison operat | and | { field: { "$lt": value1 }, field: { "$gt": value2 }, ... } | All conditions outside of $or operators will be considered as combined by an and operator. There is no explicit operator. | + Search endpoints can support filtering by variable values. This allows querying for process-related resources based on the values of specific variables that exist in their respective scope. For example, user task search supports filtering using the variables object and defining filter criteria for specific variables. diff --git a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md index cf09f60f155..4182b40ef6e 100644 --- a/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md +++ b/versioned_docs/version-8.6/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md @@ -93,7 +93,9 @@ Search endpoints can also be used to directly access entity instances with a uni Query requests consist of the components for **filter**, **sort**, and **page**. + + The filter object defines which fields should match. Only items that match the given fields will be returned. The available fields vary by object and are described in the respective search endpoint. Filtering by a unique identifier is usually available in filtering options. Beyond that, the filter options don’t have to comprise all the returned items’ attributes.