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,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[].