C8 api intermediate tutorial #5636

christinaausley · 2025-04-25T22:25:43Z

Description

Docs aligned with tutorial camunda/camunda-api-tutorials#13. This PR should not be merged until the actual tutorial is merged.

When should this change go live?

This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
This is already available but undocumented and should be released within a week. (add available & undocumented label)
This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
This is part of a scheduled alpha or minor. (add alpha or minor label)
There is no urgency with this change (add low prio label)

PR Checklist

My changes are for an upcoming minor release and are in the /docs directory (version 8.8).
My changes are for an already released minor and are in a /versioned_docs directory.

I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
- Engineering team review
- Technical writer review via @camunda/tech-writers unless working with an embedded writer.

github-actions · 2025-04-25T22:26:04Z

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

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

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md
docs/apis-tools/camunda-api-rest/sidebar-schema.js
docs/apis-tools/camunda-api-rest/tutorial.md

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

pepopowitz

❤️ No blocking feedback, this is fantastic!!!! Great work.

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

tmetzke

👍 Really cool, nothing to add besides what @pepopowitz already suggested 🚀

mesellings

Great work @christinaausley, this is really helpful for users! 🚀

Just some nitpicky, non-blocking suggestions you can either adopt or ignore, depending on your preference! 😊

mesellings · 2025-05-02T09:18:33Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+id: camunda-8-api-intermediate-tutorial
+title: Intermediate tutorial
+sidebar_label: Intermediate
+description: "Step through our intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."


Suggested change

description: "Step through our intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."

description: "Step through this intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."

Rewording suggestion

mesellings · 2025-05-02T09:23:53Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+---
+
+In this tutorial, we'll step through examples to highlight the capabilities of the Camunda 8 API, such as deploying resources, creating and starting a process instance, and viewing a process instance by its key.
+


Could add an "About this tutorial" section here, that includes who this is aimed at, link back to the beginner tutorial for example, and describe what is achieved at the end of the tutorial - like a learning statement at the beginning of a lesson (already covered in the intro sentence, but perhaps more detail).

mesellings · 2025-05-02T09:24:57Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+sidebar_label: Intermediate
+description: "Step through our intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."
+---
+


Could add an intermediate badge, as per the Get Started guides?

mesellings · 2025-05-02T09:26:19Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+
+In this tutorial, we'll step through examples to highlight the capabilities of the Camunda 8 API, such as deploying resources, creating and starting a process instance, and viewing a process instance by its key.
+
+## Prerequisites


Could make this section into a table layout to make it easier to see, as it is quite cluttered atm with a lot of information. For example, https://docs.camunda.io/docs/next/components/modeler/web-modeler/idp/idp-configuration/#prerequisites.

mesellings · 2025-05-02T09:27:08Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+Make sure you keep the generated client credentials in a safe place. The **Client secret** will not be shown again. For your convenience, you can also download the client information to your computer.
+:::
+
+- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.


Suggested change

- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.

- In this tutorial, we use a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.

Rewording suggestion for plain English - I always trya nd avoid utilize where use can do the same job 😊

mesellings · 2025-05-02T09:32:25Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+
+If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client ID and client secret. Then, we return the actual token that can be passed as an authorization header in each request.
+
+To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add the following:


Suggested change

To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add the following:

To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. Add the following environment variables:

mesellings · 2025-05-02T09:33:17Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+
+These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites).
+
+Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.


Suggested change

Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.

See the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.

mesellings · 2025-05-02T09:36:07Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+9. In your terminal, run `node cli.js processInstances deploy`.
+
+:::note
+This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with roles in this tutorial, you may add additional arguments depending on the API calls you would like to make.


Suggested change

This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with roles in this tutorial, you may add additional arguments depending on the API calls you would like to make.

This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with roles in this tutorial, you may add additional arguments depending on the API requests you want to make.

Should we use request in place of call?

mesellings · 2025-05-02T09:37:09Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+
+4. In your terminal, run `node cli.js processInstances view <key>`, where `<key>` is the process instance key. The `processDefinitionName` and `state` will then display in the output.
+
+## If you get stuck


Suggested change

## If you get stuck

## Troubleshooting

mesellings · 2025-05-02T09:38:30Z

docs/apis-tools/camunda-api-rest/intermediate-tutorial.md

+- If you haven't done so already, [create a cluster](/guides/create-cluster.md).
+- Upon cluster creation, [create your first client](/guides/setup-client-connection-credentials.md). Ensure you check the `Zeebe` client scope box.
+
+:::note


Suggested change

:::note

:::caution

Is it worth making this a caution as this is important for them to capture first-time?

christinaausley added 2 commits April 25, 2025 15:58

draft c8 api intermediate tutorial

eb26622

draft camunda 8 intermediate tutorial

6fcaf55

github-actions bot assigned christinaausley Apr 25, 2025

add to sidebar

e0eaca2

christinaausley changed the title ~~WIP: C8 api intermediate tutorial~~ C8 api intermediate tutorial Apr 28, 2025

christinaausley requested review from tmetzke, pepopowitz and a team April 28, 2025 17:53

akeller moved this to 👀 In Review in Documentation Team Apr 28, 2025

akeller added this to Documentation Team Apr 28, 2025

christinaausley marked this pull request as ready for review April 28, 2025 17:54

christinaausley added epic:api-interactivity theme:api-streamline Issues related to the theme of streamlining APIs component:api Issues related to the C8 REST API labels Apr 28, 2025

pepopowitz approved these changes Apr 28, 2025

View reviewed changes

tmetzke previously approved these changes Apr 29, 2025

View reviewed changes

resolve comments

709de24

christinaausley dismissed tmetzke’s stale review via 709de24 May 1, 2025 14:51

christinaausley requested a review from tmetzke May 1, 2025 14:51

mesellings approved these changes May 2, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

C8 api intermediate tutorial #5636

C8 api intermediate tutorial #5636

christinaausley commented Apr 25, 2025 •

edited

Loading

github-actions bot commented Apr 25, 2025 •

edited

Loading

pepopowitz left a comment

tmetzke left a comment

mesellings left a comment

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

mesellings May 2, 2025

	description: "Step through our intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."
	description: "Step through this intermediate Camunda 8 API tutorial to deploy resources, create and start a process instance, and view a process instance by its key."

		---

		In this tutorial, we'll step through examples to highlight the capabilities of the Camunda 8 API, such as deploying resources, creating and starting a process instance, and viewing a process instance by its key.


		In this tutorial, we'll step through examples to highlight the capabilities of the Camunda 8 API, such as deploying resources, creating and starting a process instance, and viewing a process instance by its key.

		## Prerequisites

	- In this tutorial, we utilize a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.
	- In this tutorial, we use a JavaScript-written [GitHub repository](https://github.com/camunda/camunda-api-tutorials) to write and run requests. Clone this repo before getting started.


		If you're interested in how we use a library to handle auth for our code, or to get started, examine the `auth.js` file in the GitHub repository. This file contains a function named `getAccessToken` which executes an OAuth 2.0 protocol to retrieve authentication credentials based on your client ID and client secret. Then, we return the actual token that can be passed as an authorization header in each request.

		To set up your credentials, create an `.env` file which will be protected by the `.gitignore` file. You will need to add the following:


		These keys will be consumed by the `auth.js` file to execute the OAuth protocol, and should be saved when you generate your client credentials in [prerequisites](#prerequisites).

		Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.

	Examine the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.
	See the existing `.env.example` file for an example of how your `.env` file should look upon completion. Do not place your credentials in the `.env.example` file, as this example file is not protected by the `.gitignore`.

	This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with roles in this tutorial, you may add additional arguments depending on the API calls you would like to make.
	This `deploy` command is connected to the `deployResources` function at the bottom of the `camunda-process-instances.js` file, and executed by the `cli.js` file. While we will work with roles in this tutorial, you may add additional arguments depending on the API requests you want to make.


		4. In your terminal, run `node cli.js processInstances view <key>`, where `<key>` is the process instance key. The `processDefinitionName` and `state` will then display in the output.

		## If you get stuck

C8 api intermediate tutorial #5636

Are you sure you want to change the base?

C8 api intermediate tutorial #5636

Conversation

christinaausley commented Apr 25, 2025 • edited Loading

Description

When should this change go live?

PR Checklist

github-actions bot commented Apr 25, 2025 • edited Loading

pepopowitz left a comment

Choose a reason for hiding this comment

tmetzke left a comment

Choose a reason for hiding this comment

mesellings left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

christinaausley commented Apr 25, 2025 •

edited

Loading

github-actions bot commented Apr 25, 2025 •

edited

Loading