W-23574307 acb tutorial

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

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.

code-builder-home/modules/ROOT/pages/tut-flights-debug-api.adoc

@@ -0,0 +1,141 @@
+= 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.
+
+. In Anypoint Code Builder, open your implementation project and verify that the listener in `american-flights-api-main` is configured for host `0.0.0.0` and port `8081`.
+. Click the *Listener* element in your flow.
+. On the *Connection Config* field, click *Edit Connection*.
+. 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*.
+. 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 the flight-by-ID response path works.
+* 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 canvas view of your `american-flights-api-implementation.xml` file.
+. Locate the flow `get:\flights\(flightId):american-flights-api-config`.
+. 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.
+. 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.
+. Click the *Start Debugging* button (green play icon).
+. Wait for the application to deploy in debug mode. You see `Debugger listening on port XXXX` in the output panel.
+
+== Step Through the Execution and Inspect Variables and Payload
+
+. After your application starts running in debug mode, send a request from your REST client:
++
+[source,command]
+----
+GET 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:
+* `attributes.uriParams.flightId`: The flight ID from the URL.
+* `attributes.headers`: HTTP headers.
+* `attributes.method`: HTTP method (GET, POST, and so on).
+. Expand *Variables* to see Mule variables created by Transform Message components:
+* `vars.flightCodeMap`: The flight code mapping.
+* `vars.dbFlightId`: The database ID for the flight.
+. To evaluate a DataWeave expression at the current breakpoint:
+.. In the Debug panel, locate the *Watch* section.
+.. Click the *+* icon to add a watch expression.
+.. 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.
+. Execution stops at the *Transform Flight* component.
+. Expand *Mule Message > Payload*.
++
+Notice that now the message contains the results from the database query.
+. Click *Stop* (SHIFT+F5) 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.
+. Inspect `vars.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 the Debug panel, expand the `error` object and verify:
+* `error.errorType`: `VALIDATION:FLIGHT_NOT_FOUND`
+* `error.description`: `"Flight code AA999 not found in our system"`
+. Inspect the Logger component's message evaluation.
+. 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[].

code-builder-home/modules/ROOT/pages/tut-flights-deploy-api.adoc

@@ -0,0 +1,89 @@
+= 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.
+. Select an environment, for example: *Sandbox*.
++
+If there's no deployment settings file for the project, Code Builder creates one.
+. In the deployment configuration file, 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-2 - 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.