Build a Feedback API Using Orkes Conductor API Gateway

This tutorial shows how to expose an Orkes Conductor workflow as a public API by using the API Gateway. You will build a simple feedback API that accepts a user rating and comment, validates the input using a schema, and triggers a workflow to process the feedback.

In this tutorial, you will:

1. Create a feedback workflow in Orkes Conductor.
2. Define an input schema for the workflow.
3. Create an application.
4. Configure authentication settings for the API service.
5. Create a feedback service.
6. Create a route.
7. Test the endpoint.

By the end of this tutorial, you will have a working API endpoint backed by an Orkes Conductor workflow.

To follow along, ensure you have access to the free Orkes Developer Edition.

Step 1: Create a feedback workflow in Orkes Conductor

In this step, you create a workflow that processes feedback submitted through an API request.

To create a workflow:

1. Go to Definitions > Workflow from the left navigation menu on your Conductor cluster.
2. Select + Define workflow.
3. In the Code tab, paste the following code:

{
 "name": "Feedback",
 "description": "Workflow to process user feedback ",
 "version": 1,
 "tasks": [
   {
     "name": "feedback_inline",
     "taskReferenceName": "formatFeedback",
     "inputParameters": {
       "evaluatorType": "graaljs",
       "rating": "${workflow.input.rating}",
       "comment": "${workflow.input.comment}",
       "expression": "(function () {\n  return {\n    message: 'Feedback received with rating ' + $.rating + ' and comment: \"' + $.comment + '\".'\n  };\n})();"
     },
     "type": "INLINE"
   }
 ],
 "inputParameters": [
   "rating",
   "comment"
 ],
 "outputParameters": {
   "message": "${formatFeedback.output.result.message}"
 },
 "schemaVersion": 2
}

4. Select Save > Confirm.

Your workflow looks like this:

In this workflow, you define the backend logic that the API Gateway will execute when a request is received.

The workflow accepts a rating and comment as input, processes the values using a simple Inline task, and returns a formatted confirmation message. This minimal design keeps the focus on API Gateway configuration while still demonstrating how workflow input and output are handled.

The workflow is now ready. The next step is to define a schema that validates incoming API requests.

Step 2: Define input schema for the workflow

The input schema ensures that only valid API requests can trigger the workflow.

To define an input schema:

1. Go to Definitions > Schema from the left navigation menu on your Conductor cluster.
2. Select + New schema.
3. In the Code tab, paste the following schema:

{
 "name": "FeedbackSchema",
 "version": 1,
 "type": "JSON",
 "data": {
   "$schema": "http://json-schema.org/draft-07/schema",
   "type": "object",
   "properties": {
     "rating": {
       "type": "integer",
       "minimum": 1,
       "maximum": 5
     },
     "comment": {
       "type": "string"
     }
   },
   "required": [
     "rating",
     "comment"
   ]
 }
}

4. Select Save > Confirm.

The next step is to create an application with permission to execute the workflow.

Step 3: Create an application

Applications act as service accounts that control which workflows the API Gateway can execute.

To create an application:

1. Go to Access Control > Applications, from the left navigation menu on your Conductor cluster.
2. Select + Create application.
3. Enter a Name for the application.
4. In Permissions, select + Add permission.
5. In the Workflow tab, select the workflow created in Step 1.
6. Enable the EXECUTE permission.
7. Select Add permissions.

The application now has permission to execute the feedback workflow.

Step 4: Configure authentication settings

Authentication settings define how clients are authorized to access the API. You can configure public authentication without a key, or you can authenticate requests by using an API key. In this example, the service uses public authentication.

To configure authentication settings:

1. Go to APIs > Authentication, from the left navigation menu on your Conductor cluster.
2. Select + New authentication.
3. Enter a unique name as the ID and select Authentication Type as Public.
4. In Application, select the application created in the previous step.

5. Select Save.

Step 5: Create a feedback service

A service represents a logical grouping of API routes that share common configuration settings.

To create a service:

1. Go to APIs > Services, from the left navigation menu on your Conductor cluster.
2. Select + New service.
3. In Service ID, enter feedback-service.
4. Enter the Display Name as Feedback Service.
5. Disable the field MCP Enabled.
6. Enter the Base Path as /api/feedback.
7. Set the Auth Config to the authentication setting created in the previous step.
8. In CORS Configuration,
   • Set Allowed Origins as *.
   • Set Allowed Methods to Select All.
   • Set Allowed Headers as *.
9. Set an optional Description for the service.

10. Select Save.

The service is now ready. Next, create a route to connect it to the workflow.

Step 6: Create a route

Routes define individual API endpoints and map them to workflows.

To create a route:

1. Go to the Services and select the + button next to the service created.

2. In Route Definition, set:
   • HTTP Method to POST.
   • Path to /user-feedback/{user-id}.
3. In Workflow Configuration, set the Workflow Name to the one created in Step 1.
4. In Schema, set the Input Schema to the schema created in Step 2.

5. Select Save.

Step 7: Test the endpoint

You can test the route directly from the Conductor UI.

Test endpoint from Conductor UI

To test a route:

1. Go to the APIs > Services, and select the service.
2. In Routes, select the play icon next to the route to test.
3. In Path Parameters, enter a sample user-id.
4. In Body, enter the request payload as defined in the workflow. For example:

{
 "rating":4,
 "comment":"Good service"
}

5. Select Test Route.
6. Review the Response to verify the route works as expected.

Verify workflow execution

To confirm that the workflow was triggered:

1. Go to Executions > Workflow.
2. Select the latest execution of the Feedback workflow.

3. Select the Workflow ID to view the execution details.
4. In the Workflow Input/Output tab, verify that the metadata was passed correctly.

Access the endpoint details

To view the endpoint details and supporting resources:

1. Go to APIs > Services, and select your service.
2. Select a route to open its details.
3. You can get the cURL command for the actual endpoint here.

You can also get the OpenAPI documentation for the service. Go to APIs > Services, and select your service. In Metadata & Resources, select View API Documentation.

When the endpoint is invoked, the workflow runs automatically. You can extend the workflow to add logic such as storing feedback, sending notifications, or triggering downstream processes.