Skip to content

Commit

Permalink
style(formatting): technical review
Browse files Browse the repository at this point in the history
  • Loading branch information
@christinaausley
christinaausley committed Dec 9, 2024
1 parent e0b223a commit a915eb1
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 71 deletions.
86 changes: 43 additions & 43 deletions docs/apis-tools/camunda-api-rest/camunda-api-rest-guidelines.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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`.

```
{
Expand All @@ -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

Expand All @@ -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
Expand All @@ -165,19 +165,19 @@ 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

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.

```
{
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Loading

0 comments on commit a915eb1

Please sign in to comment.