diff --git a/code-builder-home/modules/ROOT/assets/images/icon-apply.svg b/code-builder-home/modules/ROOT/assets/images/icon-apply.svg new file mode 100644 index 000000000..826436972 --- /dev/null +++ b/code-builder-home/modules/ROOT/assets/images/icon-apply.svg @@ -0,0 +1,3 @@ + + + diff --git a/code-builder-home/modules/ROOT/assets/images/icon-edit.svg b/code-builder-home/modules/ROOT/assets/images/icon-edit.svg new file mode 100644 index 000000000..9e8ae3a6a --- /dev/null +++ b/code-builder-home/modules/ROOT/assets/images/icon-edit.svg @@ -0,0 +1,3 @@ + + + diff --git a/code-builder-home/modules/ROOT/assets/images/icon-function.svg b/code-builder-home/modules/ROOT/assets/images/icon-function.svg new file mode 100644 index 000000000..4679f991b --- /dev/null +++ b/code-builder-home/modules/ROOT/assets/images/icon-function.svg @@ -0,0 +1,3 @@ + + + diff --git a/code-builder-home/modules/ROOT/assets/images/icon-kebab.svg b/code-builder-home/modules/ROOT/assets/images/icon-kebab.svg new file mode 100644 index 000000000..e348c1120 --- /dev/null +++ b/code-builder-home/modules/ROOT/assets/images/icon-kebab.svg @@ -0,0 +1,3 @@ + + + diff --git a/code-builder-home/modules/ROOT/assets/images/icon-text-mode.svg b/code-builder-home/modules/ROOT/assets/images/icon-text-mode.svg new file mode 100644 index 000000000..2864c3eab --- /dev/null +++ b/code-builder-home/modules/ROOT/assets/images/icon-text-mode.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-acb-activity-bar-icon.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-acb-activity-bar-icon.png new file mode 100644 index 000000000..f26ed4380 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-acb-activity-bar-icon.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-add-breakpoint.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-add-breakpoint.png new file mode 100644 index 000000000..120d84cf3 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-add-breakpoint.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-add-expression.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-add-expression.png new file mode 100644 index 000000000..69eece86a Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-add-expression.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-choice-flow-overview.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-choice-flow-overview.png new file mode 100644 index 000000000..bdeae58c5 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-choice-flow-overview.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-configure-library.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-configure-library.png new file mode 100644 index 000000000..4ed6e228d Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-configure-library.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-config.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-config.png new file mode 100644 index 000000000..255156f15 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-config.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-valid.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-valid.png new file mode 100644 index 000000000..acbae77ff Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-connection-valid.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-driver-configured.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-driver-configured.png new file mode 100644 index 000000000..4c567a96f Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-driver-configured.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flight-by-id-config.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flight-by-id-config.png new file mode 100644 index 000000000..a4bd8a204 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flight-by-id-config.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flow-overview.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flow-overview.png new file mode 100644 index 000000000..c19960005 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-flow-overview.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-library-source-maven.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-library-source-maven.png new file mode 100644 index 000000000..f4c1487a9 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-library-source-maven.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-maven-search-results.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-maven-search-results.png new file mode 100644 index 000000000..bad71fec9 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-maven-search-results.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-mysql-connection.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-mysql-connection.png new file mode 100644 index 000000000..5ca0127f6 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-mysql-connection.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-add-connection.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-add-connection.png new file mode 100644 index 000000000..bcfe2e700 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-add-connection.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-query.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-query.png new file mode 100644 index 000000000..9c135a84a Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-db-select-query.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-debug-app.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-debug-app.png new file mode 100644 index 000000000..47d572bc5 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-debug-app.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-delete-target.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-delete-target.png new file mode 100644 index 000000000..fadb58a7d Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-delete-target.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-dw-transform-config.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-dw-transform-config.png new file mode 100644 index 000000000..bbc673023 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-dw-transform-config.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-enable-text-mode.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-enable-text-mode.png new file mode 100644 index 000000000..7eb3dad5c Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-enable-text-mode.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-error-handler-add-component.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-error-handler-add-component.png new file mode 100644 index 000000000..9425144a4 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-error-handler-add-component.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-expression-mode-enabled.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-expression-mode-enabled.png new file mode 100644 index 000000000..af8f61cc6 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-expression-mode-enabled.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-flow-list-view.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-flow-list-view.png new file mode 100644 index 000000000..9c5883d5e Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-flow-list-view.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-listener-config.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-listener-config.png new file mode 100644 index 000000000..4356b668e Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-listener-config.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-new-file.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-new-file.png new file mode 100644 index 000000000..c913f4564 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-new-file.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-new-munit.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-new-munit.png new file mode 100644 index 000000000..8e1e49d03 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-new-munit.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-open-vibes.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-open-vibes.png new file mode 100644 index 000000000..1b13fbb90 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-open-vibes.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-publish-command-palette.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-publish-command-palette.png new file mode 100644 index 000000000..eb1136bd7 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-publish-command-palette.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-restricted-banner.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-restricted-banner.png new file mode 100644 index 000000000..d7851897a Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-restricted-banner.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-set-custom-metadata.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-set-custom-metadata.png new file mode 100644 index 000000000..146d1e102 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-set-custom-metadata.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-show-flow-list.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-show-flow-list.png new file mode 100644 index 000000000..f8f155c61 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-show-flow-list.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-step-over.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-step-over.png new file mode 100644 index 000000000..76aae7224 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-step-over.png differ diff --git a/code-builder-home/modules/ROOT/assets/images/tut-flights-vibes-auto-approve.png b/code-builder-home/modules/ROOT/assets/images/tut-flights-vibes-auto-approve.png new file mode 100644 index 000000000..4811361e9 Binary files /dev/null and b/code-builder-home/modules/ROOT/assets/images/tut-flights-vibes-auto-approve.png differ diff --git a/code-builder-home/modules/ROOT/nav.adoc b/code-builder-home/modules/ROOT/nav.adoc index 066e5833a..6a2d5cc7a 100644 --- a/code-builder-home/modules/ROOT/nav.adoc +++ b/code-builder-home/modules/ROOT/nav.adoc @@ -29,6 +29,15 @@ *** xref:tut-slack-add-condition-to-your-flow.adoc[] *** xref:tut-slack-configure-integration.adoc[] +** xref:tut-flights-api-tutorial.adoc[] +*** xref:tut-flights-design-api.adoc[] +*** xref:tut-flights-implement-api.adoc[] +*** xref:tut-flights-validate-transform-data.adoc[] +*** xref:tut-flights-debug-api.adoc[] +*** xref:tut-flights-munit-test-api.adoc[] +*** xref:tut-flights-deploy-api.adoc[] +*** xref:tut-flights-manage-secure-monitor-api.adoc[] + * xref:ai-enabling-api-project-topic-center.adoc[] // USE AI TO DESIGN AN API SPEC diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-api-tutorial.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-api-tutorial.adoc new file mode 100644 index 000000000..9f742a78d --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-api-tutorial.adoc @@ -0,0 +1,39 @@ += Build an API from Start to Finish with Anypoint Code Builder +:imagesdir: ../assets/images +:page-pagination: next + +Take an end-to-end, API-led journey in MuleSoft: design a REST API specification, implement it as an integration, debug and test your application, deploy it, and then manage and monitor it in production. This tutorial walks you through that full lifecycle using a single-resource API, the American Flights API, that returns flight information from a MySQL database. + +After you complete the tutorial with this single-resource API, use the same model to plan your own connectivity projects. + +This tutorial series contains the following parts: + +. xref:tut-flights-design-api.adoc[] + +Design the American Flights API specification, test it with the built-in mocking service, and publish it to Anypoint Exchange. +. xref:tut-flights-implement-api.adoc[] + +Scaffold the specification into an integration project and connect to a MySQL database. +. xref:tut-flights-validate-transform-data.adoc[] + +Add business logic validation and transform database records to meet the API contract. +. xref:tut-flights-debug-api.adoc[] + +Run the application locally and use the debugger to trace request execution and error routing. +. xref:tut-flights-munit-test-api.adoc[] + +Create and run MUnit tests to verify your API behaves correctly. +. xref:tut-flights-deploy-api.adoc[] + +Deploy the application to CloudHub 2.0. +. xref:tut-flights-manage-secure-monitor-api.adoc[] + +Register the API with API Manager, secure it with a policy, and monitor it with Runtime Manager. + +== Before You Begin + +Before you begin your API journey, verify that you have the required tools and access: + +* Set up your MuleSoft environment. ++ +See xref:start-acb.adoc[] for more information. +* Create an account on Anypoint Platform. ++ +Use your username and password for your Anypoint Platform organization. If you don't have an Anypoint Platform account yet, create a trial organization. +* Download a REST client, such as Advanced REST Client or another similar client, to test REST requests. This tutorial uses Advanced REST Client. +* Have some familiarity with xref:access-management::business-groups.adoc[business groups]. API specs must belong to a business group to be published to Exchange. + +TIP: Configure a long timeout in your REST client settings to avoid timeout issues during debugging. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-debug-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-debug-api.adoc new file mode 100644 index 000000000..5db33499b --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-debug-api.adoc @@ -0,0 +1,152 @@ += Debug the American Flights API +:imagesdir: ../assets/images +:page-pagination: + +After implementing your API flows, validate that the application behaves as expected before writing automated tests. In this section, you run the project locally and use the debugger to trace request execution and error routing. + +== Run the Application Locally + +Before testing your API, start the Mule application locally to verify the implementation works as designed. + +. Open the `american-flights-api-main` flow. +. Click the *Listener* element. +. On the *Connection Config* field, click *Edit Connection* (image:icon-gear.png["The Edit Connection icon.",1.5%, 1.5%]). ++ +image::tut-flights-listener-config.png["The Listener properties panel with Edit Connection selected next to the Connection Config field"] +. Verify the values and update them if necessary: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Host* | `0.0.0.0` +| *Port* | `8081` +|=== ++ +// Pointer to Run and Debug +include::partial$acb-reusable-steps.adoc[tags="open-run-debug"] +. In the top menu, ensure *Run Mule Application* is selected and click *Start Debugging* (image:icon-start-debug.png["The Start Debugging icon.",1.5%, 1.5%]). +. Wait for the application to deploy. You see deployment messages in the *Output* panel. ++ +When deployment is complete, you see a message similar to: ++ +[source,command] +---- +********************************************************************** +* - - + APPLICATION + - - * - - + STATUS + - - * +********************************************************************** +* american-flights-api-implementation-1.0.0 * DEPLOYED * +********************************************************************** +---- +. In your REST client (such as Advanced REST Client), test your API endpoints: +* Send `GET http://localhost:8081/api/flights` and verify a `200` response with flight data. +* Send `GET http://localhost:8081/api/flights/AA123` and verify a `200` response with data for flight with `"ID": 1`. +* Send `GET http://localhost:8081/api/flights/123` and verify a `400` response from your API specification's path parameter validation. + +== Understand the Debugger + +The built-in debugger in Anypoint Code Builder helps you understand how your Mule application processes requests, inspect variable values at runtime, and trace error-handling paths. + +Breakpoints pause execution at specific components in your flow, so you can inspect the current state of the message payload, attributes, and variables. There are two types of breakpoints: + +* *Component Breakpoint*: Pauses execution before a specific component executes (such as a Transform Message or Database Select operation). +* *Error Breakpoint*: Pauses execution when an error occurs, allowing you to inspect the error object. + +When the application running in debug mode reaches a component with a breakpoint, execution pauses and the IDE highlights the current component with a yellow border. + +The *Debug* panel opens automatically, showing the current values of Mule variables, message attributes, payload, and the flow execution path leading to the current breakpoint. + +== Set Component Breakpoints + +Set breakpoints in your application to pause execution and evaluate values at runtime. + +. With your application stopped, open the `get:\flights\(flightId):american-flights-api-config` flow. +. Right-click the *Flight by ID* Database Select operation. +. Select *Add Breakpoint* from the context menu. ++ +A red dot appears on the component, indicating an active breakpoint. ++ +image::tut-flights-add-breakpoint.png["The get:\flights\(flightId):american-flights-api-config flow with breakpoints set on the Flight by ID Database Select and Transform Flight components"] +. Add a breakpoint on the *Transform Flight* component after the database query to inspect the payload. + +== Start a Debug Session + +. Click the *Run and Debug* icon in the activity bar. +. Ensure *Debug Mule Application* is selected in the dropdown. ++ +image::tut-flights-debug-app.png["The Run and Debug dropdown with Debug Mule Application selected"] +. Click the *Start Debugging* button (green play icon). +. Wait for the application to deploy in debug mode. + +== Step Through the Execution and Inspect Variables and Payload + +. After your application starts running in debug mode, send a GET request from your REST client to your local application: ++ +[source,command] +---- +http://localhost:8081/api/flights/AA123 +---- ++ +The execution pauses at the *Flight by ID* breakpoint. +. In the *Variables* section of the Debug panel, expand *Mule Message > Payload*. ++ +At this point, the message is empty because the query to the database hasn't executed. +. Expand *Mule Message > Attributes* to see HTTP request information: +* `uriParams.flightId`: The flight ID from the URL. +* `headers`: HTTP headers. +* `method`: HTTP method (GET, POST, and so on). +. Expand *Variables* to see Mule variables created by Transform Message components: +* `flightCodeMap`: The flight code mapping. +* `dbFlightId`: The database ID for the flight. +. To evaluate a DataWeave expression, in the Debug panel, locate the *Watch* section. +. Click *Add Expression* to add a watch expression. ++ +image::tut-flights-add-expression.png["The Watch section with the Add Expression icon highlighted"] ++ +If the button doesn't show, collapse and expand the *Watch* section so it shows again. +. Enter a DataWeave expression, such as: ++ +[source,dataweave] +---- +attributes.uriParams.flightId +---- +. Press Enter. ++ +The IDE evaluates the expression and displays the result. +. Click *Step Over* (or press F10) to continue the execution. ++ +image::tut-flights-step-over.png["The Step Over button in the debug toolbar"] +. Execution stops at the *Transform Flight* component. +. Expand *Mule Message > Payload*. ++ +Notice that now the message contains the results from the database query. +. Click *Disconnect (SHIFT+F5)* (image:icon-stop.png["The Disconnect icon.",1.5%, 1.5%]) to finish debugging. + +== Debug Error Paths + +To understand how your API handles errors, debug the validation and error-handling logic. + +. Set breakpoints on: +* The Choice router in `get:\flights\(flightId):american-flights-api-config`. +* The Raise Error component inside the *When* path. +. Start debugging and send an invalid request in your REST client: ++ +[source,command] +---- +GET http://localhost:8081/api/flights/AA999 +---- ++ +The execution pauses at the Choice router. +. In *Variables*, inspect `dbFlightId` (should be `null` because `AA999` isn't in the mapping). +. Click *Step Over* (F10). ++ +Execution moves to the *When* path and pauses at Raise Error. +. Click *Step Over* (F10). ++ +Execution pauses at the On Error Propagate handler for `VALIDATION:FLIGHT_NOT_FOUND`: +. In *Parameters*, verify: +* `type`: `VALIDATION:FLIGHT_NOT_FOUND` +* `description`: `"Flight code AA999 not found in our system"` +. Click *Continue* (F5) to complete the error response. + +Once your application behaves as expected, add automated tests in xref:tut-flights-munit-test-api.adoc[]. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-deploy-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-deploy-api.adoc new file mode 100644 index 000000000..1ec1f6ac6 --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-deploy-api.adoc @@ -0,0 +1,90 @@ += Deploy the American Flights API to CloudHub 2.0 +:imagesdir: ../assets/images +:page-pagination: + +After implementing, debugging, and testing your API locally, you're ready to deploy it to CloudHub 2.0. CloudHub 2.0 is MuleSoft's cloud-based integration platform that lets you deploy, manage, and scale your Mule applications without managing infrastructure. + +In this section, you deploy your American Flights API to CloudHub 2.0. You configure it in API Manager, apply a security policy, and monitor its performance using Runtime Manager in the pages that follow. + +CloudHub 2.0 provides a fully managed, containerized deployment environment for your Mule applications. Deploying from Anypoint Code Builder is a streamlined process that packages your application and deploys it directly to the cloud. + +See xref:int-deploy-mule-apps.adoc[] for more information about CloudHub and CloudHub 2.0 deployment concepts. + +== Prerequisites for Deployment + +Before deploying to CloudHub 2.0, verify that you have: + +* A CloudHub 2.0 account with available vCores (virtual cores) for deployment. +* Runtime Manager permissions to read, create, and delete applications. +* An application that passes all MUnit tests. +* An application that runs successfully in debug mode locally. + +== Configure Deployment Settings and Deploy Your Project + +The first time you deploy an application to CloudHub 2.0, Anypoint Code Builder creates a deployment settings file. After modifying the deployment settings, deploy your project with those settings. + +. In the project explorer, Right-click the American Flights project XML file and select *Mule > Deploy Mule Project to CloudHub*. +. If prompted, sign in to Anypoint Platform. +. Select *CloudHub 2.0*. +. Select a deployment target, for example: Cloudhub-US-East-1 - Shared Space. +. Select an environment, for example: *Sandbox*. ++ +If there's no deployment settings file for the project, Code Builder creates one. +. Edit the deployment configuration file and provide the following information: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *applicationName* | Enter a unique name for your deployment (for example, `american-flights-api-yourname`). This name must be unique across all CloudHub deployments. +| *runtime* | Confirm the Mule runtime version (the latest compatible version is selected by default). +| *replicas* | `1`. The number of replica instances to deploy. +| *replicaSize* | `0.1`. The compute capacity (vCores) allocated to each replica. +| *deploymentModel* | Leave the default value: `rolling`. +|=== + +. Click *Deploy* in the notification pop-up. ++ +If the notification is no longer visible, restart the deployment from the first step. +. Select the Mule version to use for the deployment. +. If prompted to select an asset version, leave the default value and press Enter. + +NOTE: Worker size and count affect your CloudHub 2.0 costs. For this tutorial, use 0.1 vCores with 1 worker, which are the minimum allowed values. + +The deployment process starts and usually takes from two to five minutes. After this period, look for an ACB notification with a message similar to this: `The 'american-flights-api-implementation' project was published to the 'Sandbox' environment in CloudHub 2.0 'Cloudhub-US-East-1 - Shared Space'. The deployment is now processing. Monitor its progress in Runtime Manager.` + +== Monitor the Deployment Process + +After initiating the deployment, open Runtime Manager to monitor the status. + +. In the notification that shows after deployment starts, click *Open Runtime Manager* and then click *Open*. ++ +Alternatively, if you missed the notification, open xref:runtime-manager::index.adoc[Runtime Manager] and search for your application name. Then, click the application name to open its status page. +. Confirm the *Application status* is *Running*. ++ +If the application is still deploying and shows status *Not Running*, wait a few minutes for the process to finish. + +== Verify Your Deployed Application + +Once deployed, verify that your API is accessible and functioning correctly. + +. In Runtime Manager, copy the application URL from the *Public endpoint* value. ++ +The URL is similar to this: `https://american-flights-api-implementation-ij0c18.5sc6y6-3.usa-e2.cloudhub.io` +. In your REST client, test the deployed API by making a GET request to your endpoint and adding `/api/flights` to the URL. For example: ++ +[source,command] +---- +GET https://american-flights-api-implementation-ij0c18.5sc6y6-3.usa-e2.cloudhub.io/api/flights +---- ++ +Replace the URL from the example with your actual endpoint URL. +. Verify that you receive a `200 OK` response with the flight data. +. Test additional endpoints: ++ +[source,command] +---- +GET https://american-flights-api-implementation-ij0c18.5sc6y6-3.usa-e2.cloudhub.io/api/flights/AA123 +---- + +TIP: Save your application URL for use in the next sections where you configure API Manager and apply policies. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-design-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-design-api.adoc new file mode 100644 index 000000000..8aa934f59 --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-design-api.adoc @@ -0,0 +1,143 @@ += Design and Publish the American Flights API Specification +:imagesdir: ../assets/images +:page-pagination: + +Design the American Flights API specification in Anypoint Code Builder, test it with the built-in mocking service, and publish it to Anypoint Exchange so other team members can find and implement it. + +Before you begin, complete the setup in xref:tut-flights-api-tutorial.adoc[]. + +== Create the API Specification + +Start creating the American Flights API spec: + +// Open the ACB IDE +include::partial$acb-reusable-steps.adoc[tags="open-ide"] ++ +image::tut-flights-acb-activity-bar-icon.png["Anypoint Code Builder icon in the VS Code activity bar"] +. From *Create*, click *Design an API*. +. Configure your API spec project using these values: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Enable this API for Topics and Actions* | Select this checkbox to add the applicable agent topic metadata and apply centralized governance rulesets to the project. +See xref:ai-enabling-api-project-topic-center.adoc[] for more information. +| *Project Name* | `American Flights API` +| *Project Location* | Your home directory is selected by default. +This is the root folder of your project, which acts as your workspace. Don't select a different project directory for this API spec. See xref:start-add-folders.adoc[] for more information. +| *API Type* | *REST API* +| *API Specification Language* | *OAS 3.0 (YAML)* +| *Business Group* | Select the business group to use for this project. +|=== + +. Click *Create Project* to generate the American Flights API project file: `american-flights-api.yaml`. ++ +The file name is based on the project name you provide. +. Configure the agent topic metadata and instructions by setting these values: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Topic Label* | American Flights API +| *Classification Description* | Use the API description. +| *Scope* | Your job is only to book, update, or retrieve flight information. +| *Instruction* | If a user asks to retrieve flight details, use the get flight operation to retrieve information using the booking ID. +|=== ++ +If you don't see the *Agent Topics* after creating the project, you must trust the workspace folder. You can do so by clicking *Manage* then *Trust* from the notification that shows. ++ +image::tut-flights-restricted-banner.png["The workspace trust notification with Manage and Trust options"] ++ +[TIP] +If you closed the notification, or it doesn't show, see: https://code.visualstudio.com/docs/editing/workspaces/workspace-trust#_trusting-a-workspace[Trusting a workspace] for instructions. +. Click *Apply* to save your changes. +. Open MuleSoft Vibes from the toolbar. ++ +If you don't see the MuleSoft Vibes icon, click *Additional Views* to expand the toolbar. ++ +image::tut-flights-open-vibes.png["Additional Views menu with MuleSoft Vibes highlighted"] +. Enable auto-approve by clicking the *Auto-approve* section at the end of the MuleSoft Vibes window, and then select: +** *Read project files* +** *Edit project files* +** *Execute safe commands* +** *Use MCP Servers* ++ +image::tut-flights-vibes-auto-approve.png["Auto-approve panel with Read project files, Edit project files, Execute safe commands, and Use MCP servers checkboxes selected"] ++ +With auto-approve enabled, MuleSoft Vibes automatically applies changes to your project without prompting you for confirmation. See xref:vibes-get-started.adoc[] for more information. +. Enter this prompt, and then send your message: ++ +[source,command] +---- +Create an API specification example for the American Flights API that returns flight information from a MySQL database. The API must define: +1. A GET /flights endpoint that retrieves all flights. +2. A GET /flights/{flightId} endpoint that retrieves a single flight by its flightId path parameter. The flightId must match the pattern ^[A-Z]{2}[0-9]{1,4}$. +3. Both endpoints must return flight objects with this exact structure: ID (integer), code (string), price (number), departureDate (string), origin (string), destination (string), emptySeats (integer), and a nested plane object with type (string) and totalSeats (integer). +---- ++ +MuleSoft Vibes generates the spec and saves it to your file. ++ +Because MuleSoft Vibes is an AI-driven tool, the generated spec's flow and operation names may still vary between runs. Later steps account for this and tell you how to locate the correct flow. ++ +[TIP] +==== +If you get an `API streaming failed` error, click *Resume Task* to retry creating the spec. + +If you see this message: `The model has determined this command requires explicit approval.`, click *Run Command*. +==== + +== Mock and Test the API + +Next, use MuleSoft Vibes and the built-in mocking service in the API Console to test the API before you publish it. + +. Enter this prompt, and then send your message: ++ +[source,command] +---- +Test the API using the built-in mocking service in API console. +---- +. Click *Approve* every time MuleSoft Vibes asks for approval to continue with the task. + +Your API spec is now ready to publish to Anypoint Exchange. + +== Publish the API Spec to Exchange + +Publish the American Flights API spec to Exchange so that other team members can find and implement it. + +// Pointer to Command Palette +include::partial$acb-reusable-steps.adoc[tags="open-command-palette"] +. Provide this command: ++ +[source,command] +---- +MuleSoft: Publish API Project to Exchange +---- ++ +image::tut-flights-publish-command-palette.png["Command Palette with MuleSoft: Publish API Project to Exchange highlighted"] +. If prompted, click *Allow*, and follow the prompts to sign in to Anypoint Platform. +. If you haven't selected a business group, select one now in *Select a Business Group*. +. Enter the asset version: `1.0.0`. +. Enter the API version: `v1`. +. Confirm the asset ID in the project metadata: `american-flights-api`. +. Click *Publish*. ++ +The status bar shows the progress after the API is published successfully to Exchange. +. When prompted to implement the API now, select *No* to avoid scaffolding the American Flights API spec into your integration. ++ +Selecting *Yes* scaffolds the API spec into your project. Instead of scaffolding now, you scaffold the API in xref:tut-flights-implement-api.adoc[]. + +=== Locate Your API in Exchange + +After publishing your API spec, you can find it in Anypoint Exchange: + +. Navigate to Anypoint Exchange. ++ +-- +// Pointer to Exchange URLs +include::partial$acb-reusable-steps.adoc[tags="exchange-urls"] +-- +. Type `american` in the search bar and press Enter. +. Notice that your API spec is listed as an asset. ++ +You can select the API, navigate through its summary, and see all the endpoints you defined in the previous tasks. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-implement-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-implement-api.adoc new file mode 100644 index 000000000..562524ae1 --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-implement-api.adoc @@ -0,0 +1,114 @@ += Implement the American Flights API +:imagesdir: ../assets/images +:page-pagination: + +After designing and publishing your API specification, you're ready to implement it in Anypoint Code Builder. At this stage of the tutorial, you already have an API specification for the American Flights API published to Anypoint Exchange, and you're working in the same workspace where you build the integration. + +To implement the API, you scaffold the API specification into an integration project. Scaffolding generates the API interface based on the specification, creating the flows and configuration that you then extend with application logic. + +== Scaffold the American Flights API into an Integration Project + +Now that the American Flights API specification is available in Anypoint Exchange, scaffold it into a new integration project to generate the API interface. + +include::partial$acb-reusable-steps.adoc[tags="open-command-palette"] +. Provide this command: ++ +[source,command] +---- +MuleSoft: Implement an API Specification +---- +. In the *Implement an API Specification* tab that opens: +.. Provide a new name for the implementation project. +.. Select or create a new project location. +.. In the search box, type `American Flights API`, or the name you used when creating the specification, and press Enter. +.. Find your API specification on Anypoint Exchange, and click *Add Asset* to insert the API name into the field. +.. Select an existing workspace, or create a new one by providing a name and a location. +.. Click *Create Project* to start scaffolding the specification into a new implementation project. +.. If you see this notification, trust your workspace by clicking *Manage* then *Trust*. ++ +image::tut-flights-restricted-banner.png["The workspace trust notification with Manage and Trust options"] + +After scaffolding completes, confirm that the generated project contains listener configuration, APIKit router flows, and operation-specific flow stubs. + +image::tut-flights-flow-list-view.png["Flow list showing the scaffolded american-flights-api-main flow with a Listener and Router, alongside error handler flows"] + +== Connect to a Database Using the Database Connector + +Add and configure a Database Select operation to retrieve flight data from a database. + +. Open the `get:\flights:american-flights-api-config` flow. ++ +If you don't see the flow list, click *Show flow list* to display it. ++ +image::tut-flights-show-flow-list.png["The Show flow list button in Anypoint Code Builder used to display the list of flows in the canvas"] +. Click *Add Component* (+) before the existing *Transform Message* and select *Connectors > Database > Select*. ++ +If there's no *Transform Message*, add the *Database - Select* component at the beginning of the flow. You add or configure the Transform Message component later in this section. +. Click the *Select* component to open its properties panel. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]), change it to `All Flights`, then click *Apply* (image:icon-apply.svg["The Apply icon.",1.5%, 1.5%]). +. In the *Select* component properties, click *Add New Connection* next to *Connection Config*. ++ +image::tut-flights-db-select-add-connection.png["Database - Select properties panel with the Add New Connection link next to Connection Config"] +. Set the connection to *MySQL Connection*. ++ +image::tut-flights-db-mysql-connection.png["Connection Config dialog with Name set to Config and Connection set to MySQL Connection"] +. Click *Configure library* next to *MySQL JDBC Driver*. ++ +image::tut-flights-db-configure-library.png["Required Libraries section with the Configure library option next to MySQL JDBC Driver"] +. In the *Select Library Source* drop-down menu, select *Maven Dependency*. ++ +image::tut-flights-db-library-source-maven.png["Select Library Source drop-down menu set to Maven Dependency"] +. Enter `mysql:` in the *Search Maven Central Repository* text field, and select *mysql:mysql-connector-java* in the results. ++ +image::tut-flights-db-maven-search-results.png["Search Maven Central Repository results showing mysql:mysql-connector-java and other matches"] +. Enter `8.0.30` in the *Version* text field, and click *Apply*. +. Confirm that the MySQL JDBC Driver is set. ++ +image::tut-flights-db-driver-configured.png["Required Libraries section confirming MySQL JDBC Driver is set to mysql:mysql-connector-java:8.0.30"] +. Set the following configuration values: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Host* | `iltdb.mule-training.com` +| *Port* | `3306` +| *User* | `mule` +| *Password* | `mule` +| *Database* | `training` +|=== ++ +image::tut-flights-db-select-query.png["Connection Config dialog with Host, Port, User, Password, and Database fields set"] + +. Click *Test Connection* and confirm that you see a *Connection is valid* message. ++ +image::tut-flights-db-connection-valid.png["Connection is valid confirmation message"] ++ +[TIP] +If the test fails, verify the connection details and retry. If you are using a VPN, confirm that it is not preventing the connection to the MySQL database. +. Click *Apply* and close the *Database - Select* config tab. +. In the *Database - Select* properties panel, add this query in the *SQL Query Text* field: ++ +[source,sql] +---- +SELECT * FROM american +---- ++ +image::tut-flights-db-connection-config.png["Database - Select properties panel with the General tab showing the SQL Query Text field set to SELECT * FROM american"] ++ +This query selects all records from the `american` table. +. Locate the *Transform Message* component after the *All Flights* Database Select. ++ +If there's no *Transform Message* component there, click *Add Component* (+) after *All Flights* and select *Core Processors > Components > Transform Message*. ++ +image::tut-flights-db-flow-overview.png["The get:\flights:american-flights-api-config flow with an All Flights Database Select component followed by a Transform Message component"] +. Click the *Transform Message* component to open its properties panel. +. In the *Inline Script* field, set the script to: ++ +[source,dataweave] +---- +%dw 2.0 +output application/json +--- +payload +---- diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-manage-secure-monitor-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-manage-secure-monitor-api.adoc new file mode 100644 index 000000000..5cf72db2a --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-manage-secure-monitor-api.adoc @@ -0,0 +1,260 @@ += Manage, Secure, and Monitor the American Flights API +:imagesdir: ../assets/images +:page-pagination: prev + +After deploying your American Flights API to CloudHub 2.0, register it with API Manager to apply governance policies, secure it with a policy, and monitor its performance and health with Runtime Manager. + +== Create an API Instance and Link it with Your Application + +Use xref:api-manager::api-instance-landing-page.adoc[API Manager] to manage, monitor, and secure your APIs. After deploying your application to CloudHub 2.0, configure autodiscover to register it with API Manager to apply governance policies, track usage, and control access. + +=== Step 1: Navigate to API Manager + +. Sign in to Anypoint Platform. ++ +-- +include::partial$acb-reusable-steps.adoc[tags="platform-urls"] +-- ++ +. From the Anypoint Platform home page, click *Agents & Tools* > *API Manager* in the navigation menu. +. Ensure you are working on the same environment where you deployed your application (for example, Sandbox). + +=== Step 2: Create an API Instance + +Create an API instance that links your deployed application to the API specification you published earlier. + +. In API Manager, click *Add* and select *Add new API*. +. In the runtime section, select *Mule Gateway* and click *Next*. +. In the *API* section: +.. Click *Select API from Exchange*. +.. Search for "American Flights API" (the API specification you published earlier). +.. Select your API and click *Next*. +. In the *Downstream* section, click *Next*. +. In the *Upstream* section, set the Upstream URL to your application's public endpoint (the one you see in *Runtime Manager*). ++ +For example: `https://american-flights-api-implementation-ij0c18.5sc6y6-3.usa-e2.cloudhub.io/`. Click *Next*. +. In the *Review* section, click *Save* to create the API instance. ++ +Verify that your API status now shows *Active*. +. Copy your API Instance ID for use in the next step while configuring API Autodiscovery. + +=== Step 3: Configure API Autodiscovery + +API Autodiscovery links your running application to the API instance you created in the previous step, so API Manager and Runtime Manager can report accurate status and enforce policies against the correct application. + +. Open your project in Anypoint Code Builder. +. Open MuleSoft Vibes. +. Send this message: ++ +[source,command] +---- +Enable API autodiscovery for my current project with this info: +- API Instance ID: {your_api_instance_id} +- Environment: {environment} +---- ++ +NOTE: Replace `{your_api_instance_id}` with the ID you copied in the previous step, and `{environment}` with the environment you used to deploy your application (for example, Sandbox). +. Save your project and redeploy your application. ++ +When prompted for the asset version, specify `1.0.1` so you can identify the updated deployment when monitoring it in Runtime Manager. + +=== Step 4: Configure Business Group Credentials + +Your application needs valid Business Group credentials to connect to the API instance for autodiscovery and policy enforcement. Configure these credentials as properties in Runtime Manager. + +. Sign in to Anypoint Platform. +. Click *Access Management* in the navigation menu. +. Click *Business Groups* in the sidebar. +. Click your business group (the same one you used throughout this tutorial). +. Copy the *Client ID* and *Client Secret*. +. Open *Runtime Manager* and select your deployed application. +. On the side panel, click *Settings*. +. Ensure your application is *Stopped*. +. Add these properties: ++ +[%header,cols="30a,70a"] +|=== +| Property Key | Property Value + +| `anypoint.platform.client_id` | `{your_client_id}` +| `anypoint.platform.client_secret` | `{your_client_secret}` +|=== ++ +Replace `{your_client_id}` and `{your_client_secret}` with the values you copied. +. Click *Apply Changes*. + +After setting the properties and redeploying your application with API Autodiscovery configured, confirm that the API status shows *Active* in API Manager. + +TIP: If the status doesn't show *Active* right away, wait a few minutes, verify the properties are configured correctly in Runtime Manager, and check the status again. + +Your API is now registered with API Manager and ready for policy configuration. + +== Secure the API with a Policy + +Policies in API Manager let you enforce security, compliance, and governance rules on your API without modifying application code. In this section, you apply a Client ID Enforcement policy to secure your API. Common policies include: + +* *Client ID Enforcement*: Requires client applications to authenticate using a client ID and secret. +* *Rate Limiting*: Controls the number of requests allowed per time period. +* *IP Whitelist/Blacklist*: Restricts access based on IP addresses. +* *CORS*: Configures Cross-Origin Resource Sharing headers. +* *OAuth 2.0*: Implements OAuth 2.0 authentication and authorization. + +For this tutorial, you apply the Client ID Enforcement policy to require API consumers to register their applications. + +=== Step 1: Apply the Client ID Enforcement Policy + +. In API Manager, navigate to your American Flights API instance. +. Click the *Policies* tab. +. Click *Add Policy*. +. Search for *Client ID Enforcement*, select it, and click *Next*. +. Leave the default settings: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Credentials origin* | Select *customExpression*. +| *Client ID Expression* | `#[attributes.headers['client_id']]` +| *Client Secret Expression* | `#[attributes.headers['client_secret']]` +|=== + ++ +NOTE: This configuration requires clients to pass their credentials in HTTP headers. Alternative configurations can extract credentials from query parameters or custom locations. +. Click *Apply* to activate the policy. + +=== Step 2: Test the Policy + +After applying the policy, verify that unauthenticated requests are rejected. + +. In your REST client, send a request *without* client credentials: ++ +[source,command] +---- +GET http://american-flights-api-implementation{your_app_id}us-e2.cloudhub.io/api/flights +---- ++ +Replace this URL with your application's actual endpoint URL. +. Verify that you receive a `401 Unauthorized` response. + +Then, create a test client application to obtain credentials: + +. In Anypoint Platform, navigate to Exchange. +. Search for your "American Flights API". +. Click *Request Access*. +. In *API Instance*, select your instance. +. In *Application*, select *Create a new application*. +. Provide an application name and click *Create*. +. Click *Request Access*. +. Copy the *Client ID* and *Client Secret* provided. +. Test with credentials. In your REST client, add headers and resend the request: ++ +[source,command] +---- +GET http://american-flights-api-implementation{your_app_id}us-e2.cloudhub.io/api/flights +Headers: +client_id: +client_secret: +---- ++ +Replace this URL with your application's actual endpoint URL. +. Verify that you receive a `200 OK` response with flight data. + +Your API is now secured and requires authenticated clients to access it. + +=== Policy Best Practices + +When applying policies: + +* *Start with client authentication*: Always require client identification before exposing APIs externally. +* *Apply rate limiting*: Protect your API from abuse by limiting request rates. +* *Use layered security*: Combine multiple policies (authentication + rate limiting + IP filtering). +* *Test thoroughly*: Verify both authorized and unauthorized access scenarios. +* *Document requirements*: Inform API consumers about authentication requirements and rate limits. + +== Monitor and Manage Your Application with Runtime Manager + +xref:runtime-manager::index.adoc[Runtime Manager] is Anypoint Platform's operational dashboard for deployed applications. It provides real-time monitoring, log access, and management capabilities for applications running on CloudHub 2.0. + +Runtime Manager provides: + +* *Application Status*: Real-time status of deployed applications. +* *Performance Metrics*: CPU, memory, and network usage. +* *Logs*: Application logs and system logs. +* *Alerts*: Configurable notifications for application issues. +* *Application Management*: Start, stop, restart, and redeploy applications. +* *Scaling*: Adjust worker size and count. + +=== Step 1: Review Application Status + +. From Anypoint Platform, click *Agent & Tools > Runtime Manager* in the navigation menu. +. In the *Applications* list, locate your application (for example, `american-flights-api-yourname`). +. Click the application name. +. On the side panel, click *Dashboard* to review key information: +* *Status*: Shows whether the application is running, starting, or stopped. ++ +A green indicator with "Running" confirms your application is healthy. +* *Replicas*: Number of replicas and vCores assigned. +* *Last Updated*: When the application was last deployed or updated. +* *URL*: The application's public URL. + +=== Step 2: View Application Logs + +Logs help you troubleshoot issues and monitor application behavior. + +. In the side panel, click *Logs*. +. View recent log entries: +* *Log Level*: Filter by INFO, WARN, ERROR, or DEBUG. +* *Search*: Search for specific log messages or error codes. +* *Time Range*: Adjust the time range to view historical logs. ++ +TIP: If you don't see any entries, select a previously used Config from the dropdown menu. +. Example log entries: ++ +[source,command] +---- +[INFO] Application started successfully +[INFO] HTTP Listener on 0.0.0.0:8081 +[INFO] Deployed application: american-flights-api +---- +. Search for specific events: +* Search for "ERROR" to find errors. +* Search for "flights" to see API-related logs. +* Search for "Database" to see database operations. + +=== Step 3: Monitor Performance Metrics + +Monitor your application's resource usage to ensure it runs efficiently. + +. In the side panel, select *Dashboard*. +. Select the *Performance* tab. +. Review performance metrics such as average inbound and outbound response times. +. Select the *Infrastructure* tab. +. Review metrics such as CPU % and memory usage. + +=== Step 4: Manage Your Application + +Use Runtime Manager to control your application's lifecycle. From the application dashboard, you can: + +* *Stop*: Click *Stop* to stop the application. ++ +The application remains deployed but stops serving requests. +* *Start*: Click *Start* to start a stopped application. +* *Delete*: Click *Delete* to remove the application from CloudHub. ++ +This action is permanent and cannot be undone. +* *Update Configurations*: Click *Apply Changes* after changing configurations such as properties, to restart the application without redeploying. + +=== Step 5: Scale Your Application + +As your API usage grows, scale your application by adjusting worker size or count. + +. From the application dashboard, click *Settings*. +. In the *Deployment Target* section: +* *Replica Count*: Increase the number of workers for horizontal scaling. +* *Replica Size*: Change the worker size (for example, from 0.1 to 0.2 vCores). +. Click *Apply Changes*. +. CloudHub redeploys your application with the new configuration. + +NOTE: Scaling changes the resources allocated to your application and may affect your CloudHub costs. Monitor performance metrics before scaling to ensure it's necessary. + +This concludes the American Flights API tutorial series. You designed an API specification, implemented it as an integration, validated and transformed data, debugged and tested your application, deployed it to CloudHub 2.0, and secured and monitored it in production. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-munit-test-api.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-munit-test-api.adoc new file mode 100644 index 000000000..b928e59f7 --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-munit-test-api.adoc @@ -0,0 +1,348 @@ += Test the American Flights API with MUnit +:imagesdir: ../assets/images +:page-pagination: + +After debugging your API flows locally, add automated MUnit tests to verify behavior and guard against regressions before deployment. + +Before you begin, complete the debugging steps in xref:tut-flights-debug-api.adoc[]. + +MUnit is MuleSoft's unit testing framework for Mule applications. Use it to create automated tests that verify your API behaves correctly, without requiring external dependencies or manual testing. Anypoint Code Builder provides integrated support for creating, running, and debugging MUnit tests through a Testing panel, canvas UI, and code editor. + +An MUnit test consists of: + +* *Test Suite*: A file containing one or more tests (saved as `*-test.xml` in `src/test/munit`). +* *Test Case*: An individual test that validates a specific behavior. +* *Behavior*: Setup and teardown conditions, including mocks of external systems (like databases) to isolate the logic under test. +* *Execution*: Invokes a flow or subflow. +* *Validation*: Asserts that the result matches expectations. + +NOTE: MUnit 3.4.0 or later is required for canvas-based test suite creation in Anypoint Code Builder. + +== Create a New MUnit Test Suite + +Create a test suite to verify the `GET /flights` endpoint returns all flights. + +. Navigate to `src/test/munit` in the Explorer panel. +. Right-click the `munit` folder and select *New MUnit Test Suite File*. ++ +image::tut-flights-new-munit.png["The munit folder context menu with New MUnit Test Suite File selected"] +. Provide a name for the test suite: `american-flights-api-test.xml`. +. Press *Enter*. ++ +Anypoint Code Builder generates a new file with a basic structure. + +== Create a Test for Database Operations + +Now create your first test case to verify a database query returns flight data successfully. This test uses the actual database configuration from your implementation project. + +. Open the test file (`american-flights-api-test.xml`) in canvas view. +. Click *Build a Test* to start. +. Click the *Test* component and change its name to `test-database-query`. ++ +//// +Alternatively, in the code editor, add: ++ +[source,xml] +---- + + + +---- ++ +//// +. In the *Execution* section, click *+* and select *Connectors > Database > Select*. +. Click the *Database - Select* operation and specify these values: +* *Connection Config*: `Config` (select the existing database configuration) +* *SQL Query Text*: `SELECT * FROM american` ++ +//// +Alternatively, paste this code in your `munit:test` element in the XML config: ++ +[source,xml] +---- + + + + + +---- +//// +. In the *Validation* section, click *+* and select *MUnit Test Modules > Assert that*. +. Click the *Assert that* component and specify these values: +* *Expression*: `sizeOf(payload)` +* *Is*: `MunitTools::greaterThan(0)` +* *Message*: `Should return at least one flight` ++ +Ensure *Expression mode* (image:icon-function.svg["The Expression mode icon.",1.5%, 1.5%]) is enabled so expressions are recognized ++ +image::tut-flights-expression-mode-enabled.png["The Assert that component with Expression mode enabled"] ++ +This validation checks that the database query returned at least one record. + +== Run the Test + +// Pointer to Testing panel +//include::partial$acb-reusable-steps.adoc[tags="munit-open-testing-panel"] +//. Locate your test suite `american-flights-api-test.xml` in the Testing panel. +. In the Testing panel, click *Run all the tests in this file* (▶) and select *Run Test*. +. View the test results in the *Testing* panel. ++ +A successful test shows a green checkmark (✓) and output similar to: ++ +[source,command] +---- +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 +[INFO] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +---- +//// +=== Complete Example + +Here's the complete test structure: + +[source,xml] +---- + + + + + + + + + + + + + + + + + + + +---- +//// + +//// +== Advanced Testing: Use Mocks for API Endpoints + +While the previous example tested a database operation directly, you can also test complete API endpoints by adding an HTTP Request configuration and mocking dependencies. This approach allows your tests to run without requiring external systems like databases. + +=== Step 1: Add the HTTP Namespace + +Before using HTTP components in your test, you need to add the HTTP namespace to your test suite. + +. Open the test suite file in the XML code editor (click the ** icon to switch from canvas to code view). +. Locate the opening `` tag at the top of your file. +. Add the HTTP namespace declaration to the `` tag: +* Add `xmlns:http="http://www.mulesoft.org/schema/mule/http"` to the namespace declarations. +* Add `http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd` to the `xsi:schemaLocation` attribute. ++ +Your `` tag should look like this: ++ +[source,xml] +---- + +---- + +=== Step 2: Add the HTTP Request Configuration + +Add an HTTP Request configuration that points to your local Mule application. Copy and paste this configuration in the XML editor before your test cases: + +[source,xml] +---- + + + +---- + +=== Step 3: Add a Test for GET /flights (Success Path) + +Create a test that calls your API endpoint and mocks the database response. + +. Open the `american-flights-api-test.xml` file in the Code Editor. +. After the closing `` tag and before the `` tag, paste this code: ++ +[source,xml] +---- + + + + + + + + + + + + + + + + + + + +---- +. Confirm the test was created in the canvas view. + +NOTE: The `with-attributes` section identifies which specific Database Select operation to mock by matching the `doc:name` attribute value. Make sure the `whereValue` matches the name you gave to your Database Select component in the implementation flow. + +=== Step 4: Add a Test for Error Handling + +Add a new test to verify error handling when a flight code is not found. + +. After the last closing `` tag and before the `` tag, paste this code: ++ +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + + + + +---- + +=== Step 5: Run the Tests + +. Open the test in canvas view. +. In the Testing panel, click the *Run all tests in this file* (▶) button. +. Click *Run Test*. +. Verify the tests pass with the expected responses. +//// + +== Measure Test Coverage + +MUnit provides built-in coverage reporting that measures the percentage of event processors executed by your tests. Aim for at least 80% coverage for production APIs. + +After you run tests with coverage, you can view the results in the *Test Coverage* panel or in the console output. The Explorer panel also displays coverage metrics alongside your files, making it easy to identify which parts of your application need additional test coverage. + +To run tests with coverage: + +. In the Testing panel, click the *Run all tests in this file* (▶) button. +. Click *Run Test With Coverage*. ++ +Alternatively, right-click the test suite file in the project explorer and select *Run MUnit Test with Coverage*. + +== Best Practices for MUnit Testing + +Follow these best practices to create maintainable and effective MUnit tests: + +* *Mock external dependencies*: Always mock database connections, HTTP requests to external APIs, and file system operations to keep tests fast and reliable. +* *Test one behavior per test case*: Each test should validate a single scenario (success path, specific error condition, and so on). +* *Use descriptive test names*: Names like `get-flight-by-valid-code-returns-200` clearly indicate what the test validates. +* *Maintain test data separately*: Consider storing sample payloads in separate files in `src/test/resources` for complex data structures. +* *Run tests frequently*: Execute tests after each significant change to catch issues early. +* *Aim for high coverage*: Target at least 80% code coverage, ensuring all critical paths are tested. +* *Test error scenarios*: Don't just test the happy path — validate that your error handlers work correctly too. + +== Troubleshoot Common MUnit Issues + +When creating and running MUnit tests, you may encounter issues related to test execution, mocking, or runtime configuration. These are some common problems and their solutions to help you resolve test failures. + +=== Test Timeout Errors + +If tests fail with timeout errors: + +* Increase the timeout value in your MUnit configuration. +* Check for infinite loops or blocking operations in your flows. +* Ensure mocked components return responses quickly. + +=== Mock Not Applied + +If mocks aren't being applied: + +* Verify the `doc:name` attribute in `with-attributes` exactly matches your component's name. +* Check that the processor type (`db:select`, `ee:transform`, and so on) is correct. +* Ensure the mock is defined in the `munit:behavior` section before execution. + +=== Assertion Failures + +When assertions fail: + +* Review the expected vs. actual values in the test output. +* Add Logger components to see intermediate payload transformations. +* Use debug mode to inspect the actual payload structure at the validation point. diff --git a/code-builder-home/modules/ROOT/pages/tut-flights-validate-transform-data.adoc b/code-builder-home/modules/ROOT/pages/tut-flights-validate-transform-data.adoc new file mode 100644 index 000000000..68cc8f412 --- /dev/null +++ b/code-builder-home/modules/ROOT/pages/tut-flights-validate-transform-data.adoc @@ -0,0 +1,446 @@ += Validate Input Parameters and Transform Flight Data +:imagesdir: ../assets/images +:page-pagination: + +When you scaffold an API specification into an implementation project, APIKit automatically validates incoming requests against your API specification. This validation includes: + +* *Path parameter formats*: If your API spec defines a pattern (such as `pattern: "^[A-Z]{2}\d+$"`), APIKit validates the format automatically. +* *Required vs. optional parameters*: APIKit ensures required parameters are present. +* *Data types*: APIKit validates that parameters match their specified types (string, integer, boolean, and so on). +* *Enum values*: If your spec defines allowed values, APIKit validates against that list. + +If a request doesn't match these rules, APIKit returns a `400 Bad Request` with an appropriate error message before your flow logic even executes. + +While APIKit handles format and structural validation, you need custom validation for: + +* *Business logic rules*: Validating that a resource exists in your system (for example, "Does this flight code exist in our database?"). +* *Cross-field validation*: Rules that depend on multiple parameters. +* *External system checks*: Validating against external APIs or services. +* *Database lookups*: Confirming that identifiers correspond to actual records. + +In this section, you add business logic validation to check whether a flight code exists in your database before attempting to query for it. This prevents unnecessary database calls and provides more meaningful error messages to API consumers. + +In the American Flights API, the example database stores flights with numeric IDs (1, 2, 3), but the API exposes flight codes like `AA123`, `AA456`, and `AA789`. You need to map these codes to database IDs and validate that the flight exists before querying. + +== Create the Flight Code to Database ID Mapping + +First, create a transform that stores the mapping of flight codes to database IDs. + +. Open the `get:\flights\(flightId):american-flights-api-config` flow. ++ +Because MuleSoft Vibes generated the API spec, your implementation flows might have different names. You must locate the flow that starts with `get:\flights\` and is followed by an ID parameter such as `(ID)`, `(flightID)`, or `{flightID}`, for example. +. If the flow already contains any *Transform Message* components, select the components and press *Delete*, or click *More actions...* (image:icon-kebab.svg["The More actions menu icon."]) and select *Delete Component*. ++ +Delete any existing *Transform Messages* to start with a clean flow. +. Click *Add Component* (+) at the start of the flow and select *Core Processors > Components > Transform Message*. +. Click the *Transform Message* component to open its properties panel. +. Click *Delete Target* next to *Payload*. ++ +image::tut-flights-delete-target.png["The Transform Message General tab with Delete Target selected next to the Payload target"] ++ +This step ensures the Transform does not modify the payload. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]), change it to *Create Flight Code Map*, then click *Apply* (image:icon-apply.svg["The Apply icon.",1.5%, 1.5%]). +. In the *General* tab, under *Target*, click *Add* (+) and select *Variable*. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]) next to `vars.NewVariable1`, set the name to `flightCodeMap`, then click *Apply* (image:icon-apply.svg["The Apply icon.", 1.5%, 1.5%]). +. In the *Inline Script* field, replace the content with this DataWeave script: ++ +[source,dataweave] +---- +%dw 2.0 +output application/java +--- +{ + "AA123": 1, + "AA234": 2, + "AA345": 3, + "AA456": 4, + "AA567": 5 +} +---- + +This creates a variable `vars.flightCodeMap` that maps flight codes to their corresponding database IDs. + +NOTE: In a production application, you would typically query the database directly rather than maintaining a hardcoded map. This tutorial uses a map to clearly demonstrate the validation logic without requiring additional database queries. + +== Look Up the Database Flight ID + +Now create a second transform to look up the flight code in the mapping you just created. + +. After the *Create Flight Code Map* transform, click *Add Component* (+) and select *Core Processors > Components > Transform Message*. +. Click the *Transform Message* component to open its properties panel. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]), change it to *Lookup DB Flight ID*, then click *Apply* (image:icon-apply.svg["The Apply icon.",1.5%, 1.5%]). +. Click *Delete Target* next to *Payload*. +. In the *General* tab, under *Target*, click *Add* (+) and select *Variable*. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]) next to `vars.NewVariable1`, set the name to `dbFlightId`, then click *Apply* (image:icon-apply.svg["The Apply icon.",1.5%, 1.5%]). +. In the *Inline Script* field for this variable, paste this code: ++ +[source,dataweave] +---- +%dw 2.0 +output application/java +--- +vars.flightCodeMap[attributes.uriParams.flightId] +---- + +This script looks up the flight code from the request URL in the mapping created in the previous transform and returns the corresponding database ID. If the flight code isn't in the map, it returns `null`. + +NOTE: You cannot reference a variable in the same Transform Message where you're creating it. The variable only becomes available *after* the transform completes. By splitting the logic into two transforms, `vars.flightCodeMap` is available for use in the second transform. + +== Add a Choice Router to Validate Flight Existence + +Now add logic to check whether the flight code was found in the mapping. + +. After the *Lookup DB Flight ID* transform, click *Add Component* (+) and select *Core Processors > Flow Control > Choice*. +. Click the *When* path inside the Choice router. +. In the *When* properties panel, under *Expression*, add this condition to check if the flight code wasn't found: ++ +[source,dataweave] +---- +#[vars.dbFlightId == null] +---- + +This expression evaluates to `true` when the flight code doesn't exist in the mapping. + +== Raise an Error for Unknown Flight Codes + +When a flight code isn't found, raise a custom error instead of proceeding with the query. + +. Inside the *When* path (where the condition is true), click *Add Component* (+) and select *Core Processors > Error Handling > Raise Error*. +. In the *Raise Error* properties panel, configure: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Type* | `VALIDATION:FLIGHT_NOT_FOUND` +| *Description* | `'Flight code ' {plus}{plus} attributes.uriParams.flightId {plus}{plus} ' not found in our system'` +|=== + +This creates a custom error type that you handle in the error handler, providing a meaningful message that includes the flight code the user attempted to look up. + +== Add the Database Query to the Otherwise Path + +The database query executes when the flight exists (when `vars.dbFlightId` is not null). + +. Inside the *Otherwise* path of the Choice router, click *Add Component* (+) and select *Connectors > Database > Select*. +. Select the component and configure: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Name* | `Flight by ID` +| *Connection Config* | `Config` (your MySQL connection) +| *SQL Query Text* | `SELECT * FROM american WHERE ID = :flightId` +| *Input Parameters* | `{ 'flightId': vars.dbFlightId }` +|=== ++ +image::tut-flights-db-flight-by-id-config.png["Database - Select properties panel with Name set to Flight by ID, Connection Config set to Config, and the SQL Query Text and Input Parameters fields configured"] + +Your flow should now look like this: + +image::tut-flights-choice-flow-overview.png["The get:\flights\(flightId):american-flights-api-config flow with the Choice router's When and Otherwise paths configured with Raise Error and Database Select components"] + +== Add an Error Handler for Flight Not Found + +Now configure the error handler to return a proper 404 response when a flight isn't found. + +. In the canvas, open the `american-flights-api-main` flow (the main flow with the HTTP listener and error handler). +. After the last *Error Handler*, click *Add Component* (+). ++ +image::tut-flights-error-handler-add-component.png["The american-flights-api-main flow's Error Handler section with Add Component clicked after the last error handler"] +. Select *On Error Propagate*. +. Click the *On Error Propagate* component to open its properties panel +. Next to *Type* click the *Text Mode* button (image:icon-text-mode.svg["The Text Mode icon.",1.5%, 1.5%]) to enable it. ++ +image::tut-flights-enable-text-mode.png["The On Error Propagate properties panel with the Text Mode button next to the Type field"] +. In *Type*, paste `VALIDATION:FLIGHT_NOT_FOUND`. +. Inside this error handler, click *Add Component* (+) and select *Core Processors > Components > Logger*. +. Select the *Logger* and set these properties: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Level* | `WARN` +| *Message* | `#['Flight not found: ' ++ error.description]` +|=== ++ +This logs details about which flight was requested but not found, helping with debugging and monitoring. ++ +. After the Logger, click *Add Component* (+) and add *Core Processors > Components > Transform Message*. +. Configure the Transform Message: +.. In the *General* tab, under *Target > Payload*, set *Source* to *Inline Script*. +.. In the *Inline Script* field, set: ++ +[source,dataweave] +---- +%dw 2.0 +output application/json +--- +{ + message: error.description default "Flight not found", + flightId: attributes.uriParams.flightId +} +---- + +. Click *+Add* and select *Variable*. +. Name the variable `httpStatus` and set its value to `404`. ++ +image::tut-flights-dw-transform-config.png["The Transform Message properties panel with the error response script and the httpStatus variable set to 404"] + +This returns a JSON response with a meaningful error message and the flight ID that was requested, along with a 404 HTTP status code. + +== Transform Data to Meet the API Contract + +When building an API implementation, it's essential that your responses match the structure defined in your API specification. While the database might store data in one format, your API contract defines how that data should be presented to consumers. DataWeave transformations bridge this gap by mapping database fields to the expected API response format. + +In this section, you create a DataWeave transformation that converts database query results into the JSON format specified in your American Flights API contract. + +=== Understand the Data Mapping Challenge + +Your MySQL database stores flight information with these fields: + +.Example database record +[source,json] +---- +{ + "ID": 1, + "code1": "rree", + "code2": "0001", + "airlineName": "American Airlines", + "toAirport": "LAX", + "fromAirport": "MUA", + "takeOffDate": "2016-01-20", + "price": 541, + "planeType": "Boeing 787", + "seatsAvailable": 0, + "totalSeats": 200 +} +---- + +Your API specification defines a different structure for the response: + +[source,json] +---- +{ + "ID": 1, + "code": "AA123", + "price": 499.99, + "departureDate": "2024-12-25T10:00:00", + "origin": "SFO", + "destination": "LAX", + "emptySeats": 45, + "plane": { + "type": "Boeing 737", + "totalSeats": 150 + } +} +---- + +Notice the transformation challenges: + +. *Field name changes*: Database fields have different names than API fields: +.. `fromAirport` → `origin` +.. `toAirport` → `destination` +.. `takeOffDate` → `departureDate` +.. `seatsAvailable` → `emptySeats` +. *Field combination*: `code1` and `code2` need to be combined into a single `code` field. +. *Nested object creation*: `planeType` and `totalSeats` (flat fields in the database) must become a nested `plane` object in the API response. +. *Fields to exclude*: `airlineName` is in the database but not needed in the API response. + +=== Step 1: Add the Transform Message Component + +In your implementation flow `get:\flights\(flightId):american-flights-api-config`, add a Transform Message component after the Database Select operation. + +. Locate the `get:\flights\(flightId):american-flights-api-config` flow in your canvas. +. After the *Flight by ID* database query, click *Add Component* (+) and select *Core Processors > Components > Transform Message*. +. Click the *Transform Message* component to open its properties panel. +. Click *Edit name* (image:icon-edit.svg["The Edit Name icon.",1.5%, 1.5%]), change it to *Transform Flight*, then click *Apply* (image:icon-apply.svg["The Apply icon.",1.5%, 1.5%]). + +By default, this transform just outputs `payload`, which passes through the raw database structure without transformation. + +=== Step 2: Define Input Metadata + +To help DataWeave understand the structure of your database results, define input metadata. + +. In the project explorer, right-click the `examples` folder (`src/main/resources/examples`) and select *New File*. ++ +If the `examples` folder doesn't exist, right-click the *resources* folder (`src/main/resources`), select *New Folder*, and name it `examples`. ++ +image::tut-flights-new-file.png["The project explorer with the examples folder highlighted and New File selected from the context menu"] +. Name the file `sample-database-input.json`. +. Open the file, populate it with this sample database record, and save the file: ++ +[source,json] +---- +[ + { + "ID": 1, + "code1": "rree", + "code2": "0001", + "airlineName": "American Airlines", + "toAirport": "LAX", + "fromAirport": "MUA", + "takeOffDate": "2016-01-20", + "price": 541, + "planeType": "Boeing 787", + "seatsAvailable": 0, + "totalSeats": 200 + } +] +---- +. Open the `get:\flights\(flightId):american-flights-api-config` flow in the canvas. +. Click the *Transform Flight* element you added previously. +. Click the *Metadata* tab. +. Inside *Input* and next to *Payload: Any*, click *(No metadata selected)* > *Set custom metadata*. ++ +image::tut-flights-set-custom-metadata.png["The Input Payload metadata selector with Set custom metadata highlighted"] +. In the tab that opens, click *Create New*. +. In the *Add Custom Metadata* dialog, set: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Name* | `DatabaseFlightRecord` +| *Type* | *JSON* +| *Source* | *Example* +| *Example* a| `examples/sample-database-input.json` + +This is the example file you just created. +|=== + +. Click *Save & Close*. +. Click *Apply & Close*. + +You should now see the input payload structure in the left panel, showing all available database fields. + +=== Step 3: Define Output Metadata + +Now define the expected API response format based on your specification. + +. In the project explorer, right-click the `examples` folder (`src/main/resources/examples`) and select *New File*. +. Name the file `sample-flight-response.json`. +. Open the file, populate it with this sample API response (from your API spec), and save the file: ++ +[source,json] +---- +{ + "ID": 1, + "code": "AA123", + "price": 499.99, + "departureDate": "2024-12-25T10:00:00", + "origin": "SFO", + "destination": "LAX", + "emptySeats": 45, + "plane": { + "type": "Boeing 737", + "totalSeats": 150 + } +} +---- +. Open the `get:\flights\(flightId):american-flights-api-config` flow in the canvas. +. Click the *Transform Flight* element we added previously. +. Click the *Metadata* tab. +. Inside *Output* and next to *Payload: Any*, click *(No metadata selected)* > *Set custom metadata*. +. In the tab that opens, click *Create New*. +. In the *Add Custom Metadata* dialog, set: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Name* | `FlightResponse` +| *Type* | *JSON* +| *Source* | *Example* +| *Example* a| `examples/sample-flight-response.json` + +This is the example file you just created. +|=== + +. Click *Save & Close*. +. Click *Apply & Close*. + +The output panel now shows the expected response structure with the nested `plane` object. + +=== Step 4: Create the Field Mappings + +With both input and output metadata defined, you can now create the transformation using DataWeave's mapping features. + +[tabs] +==== +Use MuleSoft Vibes:: ++ +-- +. Open MuleSoft Vibes. +. Send this message: ++ +[source,command] +---- +In the get:\flights\(flightId):american-flights-api-config flow, open the Transform Flight component and add a transformation that maps the input metadata with the output metadata. For code, use code1 ++ code2. +---- ++ +NOTE: If you used a different flow or component name, ensure you specify it in the message so MuleSoft Vibes knows exactly which flow and components to modify. +. Wait until MuleSoft Vibes completes the task before making further changes. + +After MuleSoft Vibes finishes adding the transformation, confirm that the DataWeave script is similar to this: + +[source,dataweave] +---- +%dw 2.0 +output application/json +--- +{ + ID: payload[0].ID, + code: payload[0].code1 ++ payload[0].code2, + price: payload[0].price, + departureDate: payload[0].takeOffDate, + origin: payload[0].fromAirport, + destination: payload[0].toAirport, + emptySeats: payload[0].seatsAvailable, + plane: { + "type": payload[0].planeType, + totalSeats: payload[0].totalSeats + } +} +---- +-- + +Write the DataWeave Script Directly:: ++ +-- +You can write the complete DataWeave script in the *Script* view: + +. Click the *Script* tab in the Transform Message component. +. Replace the current content with: ++ +[source,dataweave] +---- +%dw 2.0 +output application/json +--- +{ + ID: payload[0].ID, + code: payload[0].code1 ++ payload[0].code2, + price: payload[0].price, + departureDate: payload[0].takeOffDate, + origin: payload[0].fromAirport, + destination: payload[0].toAirport, + emptySeats: payload[0].seatsAvailable, + plane: { + "type": payload[0].planeType, + totalSeats: payload[0].totalSeats + } +} +---- + +*Explanation:* + +* `code: payload[0].code1 ++ payload[0].code2` — concatenates `code1` and `code2` into a single `code` field. +* `departureDate: payload[0].takeOffDate` — renames the field from database to API format. +* `origin: payload[0].fromAirport` — maps `fromAirport` to `origin`. +* `destination: payload[0].toAirport` — maps `toAirport` to `destination`. +* `emptySeats: payload[0].seatsAvailable` — renames `seatsAvailable` to `emptySeats`. +* `plane: { ... }` — creates a nested object from flat database fields. +* `output application/json` — specifies the output format. +-- +==== \ No newline at end of file diff --git a/code-builder-home/modules/ROOT/pages/tutorials.adoc b/code-builder-home/modules/ROOT/pages/tutorials.adoc index eec2c9fae..36f334011 100644 --- a/code-builder-home/modules/ROOT/pages/tutorials.adoc +++ b/code-builder-home/modules/ROOT/pages/tutorials.adoc @@ -32,6 +32,10 @@ Scaffold an API specification into an interface to implement, and sync changes t + Implement a GraphQL API that you publish to Exchange. -* xref:tut-slack-create-escalation-api.adoc[]: +* xref:tut-slack-create-escalation-api.adoc[]: + Create an integration that notifies you through email or Slack when a new case is created in Salesforce. + +* xref:tut-flights-api-tutorial.adoc[]: ++ +Design, implement, debug, test, deploy, and secure a database-backed REST API from start to finish, using the American Flights API as an example.