diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7825f44d4..25017c9ce 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -71,8 +71,10 @@ * xref:des-designing-api-specs.adoc[] ** xref:des-create-api-specs.adoc[] ** xref:des-create-asyncapi-api-specs.adoc[] +** xref:des-design-grpc-api-spec.adoc[] ** xref:des-create-api-fragments.adoc[] ** xref:des-publish-api-spec-to-exchange.adoc[] +** xref:des-publish-grpc-api-to-exchange.adoc[] ** xref:des-govern-api.adoc[] ** xref:des-delete-api-projects.adoc[] @@ -102,6 +104,7 @@ * xref:imp-implementing-apis.adoc[] ** xref:imp-implement-api-specs.adoc[] ** xref:imp-asyncapi.adoc[] +** xref:imp-implement-grpc-api-spec.adoc[] ** xref:imp-implement-local-apis.adoc[] ** xref:imp-filter-search-results.adoc[] diff --git a/modules/ROOT/pages/_partials/acb-reusable-steps.adoc b/modules/ROOT/pages/_partials/acb-reusable-steps.adoc index 8cc4fba88..d5851ad4d 100644 --- a/modules/ROOT/pages/_partials/acb-reusable-steps.adoc +++ b/modules/ROOT/pages/_partials/acb-reusable-steps.adoc @@ -509,7 +509,7 @@ When the AsyncAPI feature is available for your organization, the Anypoint Code // // tag::start-implementation[] -. From *Quick Actions*, click *Implement an API*: +. From *Create*, click *Implement an API*: + image:anypoint-code-builder::implement-api-option-mat.png["*Implement an API* link highlighted in the *Getting Started* section"] . Complete the *Implement an API Specification* form: diff --git a/modules/ROOT/pages/_partials/acb-start-desktop.adoc b/modules/ROOT/pages/_partials/acb-start-desktop.adoc index 49bfb1d0c..9d8014c08 100644 --- a/modules/ROOT/pages/_partials/acb-start-desktop.adoc +++ b/modules/ROOT/pages/_partials/acb-start-desktop.adoc @@ -73,7 +73,7 @@ Ensure this option is checked. [[acb-menu]] image::anypoint-code-builder-view.png["MuleSoft icon for Anypoint Code Builder in the activity bar"] -. Check that the IDE loads the <> with *Quick Actions* and *Documentation* links. +. Check that the IDE loads the <>. . If you have an Anypoint Platform account running in the EU cloud, change the *Mule: Control Plane* setting to *EU cloud*. + diff --git a/modules/ROOT/pages/af-create-agent-network.adoc b/modules/ROOT/pages/af-create-agent-network.adoc index 3ad377cb2..78359a97e 100644 --- a/modules/ROOT/pages/af-create-agent-network.adoc +++ b/modules/ROOT/pages/af-create-agent-network.adoc @@ -27,7 +27,7 @@ To get started try one of these suggested prompts. . If you're not logged in, log in to your Anypoint Platform account. . In Anypoint Code Builder choose on of the following: - * In Quick Actions, select *Create an Agent Network*. + * In Create, select *Create an Agent Network*. * From the Command Palette, run this command: *MuleSoft: Create an Agent Network Project*. . Enter a name for the project and select the location to create the project. . Select the business group associated with the target space you created in xref:anypoint-code-builder::af-get-started.adoc[Get Started with Agent Networks]. The business group you select must be the same business group you selected when you created the target space. diff --git a/modules/ROOT/pages/ai-enabling-api-project-topic-center.adoc b/modules/ROOT/pages/ai-enabling-api-project-topic-center.adoc index c78bd7541..a04e996ac 100644 --- a/modules/ROOT/pages/ai-enabling-api-project-topic-center.adoc +++ b/modules/ROOT/pages/ai-enabling-api-project-topic-center.adoc @@ -41,9 +41,9 @@ See the xref:tutorials.adoc[] for details. include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] -. From *Quick Actions*, click *Design an API*: +. From *Create*, click *Design an API*: + -image::design-api-1.png["*Design an API* link highlighted in the *Quick Actions* section"] +image::design-api-1.png["*Design an API* link highlighted in the *Create* section"] . Select *Enable this API for Agent Topics and Actions*. . Complete the *API Specification* form: + diff --git a/modules/ROOT/pages/des-create-api-fragments.adoc b/modules/ROOT/pages/des-create-api-fragments.adoc index 966579e94..a0686b4df 100644 --- a/modules/ROOT/pages/des-create-api-fragments.adoc +++ b/modules/ROOT/pages/des-create-api-fragments.adoc @@ -56,9 +56,9 @@ To create an API spec fragment: include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] -. From *Quick Actions*, click *Design an API*: +. From *Create*, click *Design an API*: + -image::design-api-1.png["*Design an API* link highlighted in the *Quick Actions* section"] +image::design-api-1.png["*Design an API* link highlighted in the *Create* section"] . In *Design an API*, click the *API Fragment* tab: + image:des-api-fragment.png["API Fragment tab on the Design an API page"] diff --git a/modules/ROOT/pages/des-create-api-specs.adoc b/modules/ROOT/pages/des-create-api-specs.adoc index 783576469..bc465be3d 100644 --- a/modules/ROOT/pages/des-create-api-specs.adoc +++ b/modules/ROOT/pages/des-create-api-specs.adoc @@ -37,9 +37,9 @@ To create an API spec project in Anypoint Code Builder: include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] -. From *Quick Actions*, click *Design an API*: +. From *Create*, click *Design an API*: + -image::design-api-1.png["*Design an API* link highlighted in the *Quick Actions* section"] +image::design-api-1.png["*Design an API* link highlighted in the *Create* section"] . Complete the *API Specification* form: + diff --git a/modules/ROOT/pages/des-create-asyncapi-api-specs.adoc b/modules/ROOT/pages/des-create-asyncapi-api-specs.adoc index 32eb41f11..e3f47d158 100644 --- a/modules/ROOT/pages/des-create-asyncapi-api-specs.adoc +++ b/modules/ROOT/pages/des-create-asyncapi-api-specs.adoc @@ -32,9 +32,9 @@ To create and design an AsyncAPI spec project in Anypoint Code Builder: include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] -. From *Quick Actions*, click *Design an API*: +. From *Create*, click *Design an API*: + -image::design-api-1.png["*Design an API* link highlighted in the *Quick Actions* section"] +image::design-api-1.png["*Design an API* link highlighted in the *Create* section"] . Complete the *API Specification* form: + diff --git a/modules/ROOT/pages/des-design-grpc-api-spec.adoc b/modules/ROOT/pages/des-design-grpc-api-spec.adoc new file mode 100644 index 000000000..6778c713a --- /dev/null +++ b/modules/ROOT/pages/des-design-grpc-api-spec.adoc @@ -0,0 +1,131 @@ += Designing a gRPC API Specification with Anypoint Code Builder +:page-deployment-options: cloud-ide, desktop-ide + +include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] + +Anypoint Code Builder supports designing gRPC API specifications using Protocol Buffers (Protobuf 3). Create and edit `.proto` files, import reusable Protobuf libraries from Anypoint Exchange, and use syntax highlighting and validation. When you design or publish your spec, the IDE generates a binary descriptor (`.protobin`) so Mule runtime can consume the service metadata. + +Use the Protocol Buffers 3 (Protobuf 3) specification language to design gRPC APIs. gRPC uses HTTP/2 and supports four RPC patterns: + +* Unary +* Client streaming +* Server streaming +* Bidirectional streaming + +You author service and message definitions in `.proto` files and can reuse shared types by importing Protobuf fragments (libraries) from Exchange. + +== Before You Begin + +* xref:start-acb.adoc[]. +* Understand the basics of gRPC and Protocol Buffers (Protobuf 3). See https://grpc.io/docs/what-is-grpc/introduction/[Introduction to gRPC]. +* Have some familiarity with xref:access-management::business-groups.adoc[]. ++ +When you publish your API spec to Exchange from Anypoint Code Builder, the IDE requests the name of the business group. See xref:access-management::business-groups.adoc[]. + +== Create a New gRPC API Specification Project + +To create a gRPC API spec project in Anypoint Code Builder: + +include::partial$acb-reusable-steps.adoc[tags="open-ide"] + +. From *Create*, click *Design an API*: +. Complete the *API Specification* form: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Project Name* | Unique name for your project. + +This name is used as the API spec title in Exchange, the name of the spec file, and the name of the project's root directory. + +include::partial$acb-reusable-steps.adoc[tags="no-project-name-reuse"] +| *Project Location* | Your home directory or another directory you create. + +See xref:start-add-folders.adoc[]. + +include::partial$acb-reusable-steps.adoc[tags="proj-directory-warn"] +| *API Type* | The type of API spec to create. + +Select *gRPC API* to create a gRPC project. + +| *Specification Language* | The language for the API specification. + +Select *Protobuf 3* for gRPC API projects. +|=== +. Click *Create Project*. ++ +If prompted, trust the authors of the files in the folder. ++ +When the project is ready, the API project opens with a default `.proto` file in the Editor view. ++ +. Continue designing your gRPC API spec. ++ +As you enter elements, use xref:start-discover-ui.adoc#auto-complete[auto-complete] (or press Ctrl+Space) to display available options within the context. + +== Organize gRPC API Projects and Dependencies + +A new gRPC API project includes: + +* A root `.proto` file (for example, `main.proto` or a file named after your project) that defines your service and messages. +* A `protobuf-libraries` directory (or equivalent) for storing and organizing Protobuf fragments (reusable libraries) that you add as dependencies. + +You edit the main `.proto` file to define `service`, `rpc`, and `message` blocks. Dependencies from Exchange or local fragments are resolved from the `protobuf-libraries` area so you can reference shared message types and services across specs. + +== Import a Protobuf Library from Anypoint Exchange + +You can import reusable Protobuf libraries (fragments) from Anypoint Exchange and add them as dependencies to your gRPC API project. You can reuse message and service across multiple specifications. + +To use a Protobuf fragment published to Exchange: + +. Ensure you're logged in to Anypoint Platform. +. Open your gRPC API project. +. Add the Protobuf library as a dependency to the project. +. In Exchange or the dependency panel, search for the Protobuf library you need and add it to the project. +. After the dependency is added, the library is available under the project. +. In your main `.proto` file, use `import` to reference the library's package and message or service definitions. For example: ++ +[source,protobuf] +---- +syntax = "proto3"; + +import "path/to/library.proto"; + +service MyService { + rpc GetOrder(OrderRequest) returns (OrderResponse); +} +---- +. Save the spec. Anypoint Code Builder resolves the dependency and validates references. You can reuse messages and services from the imported library across your gRPC specs. + +== Define Technical Details for gRPC Specifications + +=== Declare Communication Patterns for gRPC Services + +Anypoint Code Builder and Mule runtime support all four gRPC RPC patterns: + +* **Unary** – Single request, single response. +* **Client streaming** – Client sends a stream of messages; server returns a single response. +* **Server streaming** – Client sends a single request; server returns a stream of messages. +* **Bidirectional streaming** – Both client and server send and receive streams of messages. + +Define these in your `.proto` file using the appropriate `rpc` declarations and stream modifiers. + +=== Verify Specification Accuracy with Syntax Validation + +Anypoint Code Builder provides syntax highlighting and validation for Protobuf 3 specifications. Validation is performed using the API Modeling Framework (AMF) parser, so you get inline feedback and error reporting as you edit your `.proto` files. Use the editor and the xref:start-open-output-panel.adoc[output panel] to track validation and scaffolding status. + +== Generate Binary Descriptors for Implementation + +During the design or publish process, Anypoint Code Builder generates a binary descriptor file (`.protobin`) from your Protobuf specification. With this descriptor, Mule runtime can understand the gRPC service metadata (services, methods, and message types) so you can implement and run the API. The generation typically occurs when you save, build, or publish the API spec. Don't create the `.protobin` file manually. + +== See Also + +// TODO: Include a link to gRPC Connector docs. +* xref:start-acb.adoc[] +* xref:imp-implement-grpc-api-spec.adoc[] +* xref:des-designing-api-specs.adoc[] +* xref:des-create-api-specs.adoc[] +* xref:des-create-api-fragments.adoc[] +* xref:des-publish-grpc-api-to-exchange.adoc[] +* xref:des-publish-api-spec-to-exchange.adoc[] +* xref:start-discover-ui.adoc#use-autocomplete[Use Auto-Complete in the Editors] diff --git a/modules/ROOT/pages/des-designing-api-specs.adoc b/modules/ROOT/pages/des-designing-api-specs.adoc index 6a8f4d3c6..496b6c247 100644 --- a/modules/ROOT/pages/des-designing-api-specs.adoc +++ b/modules/ROOT/pages/des-designing-api-specs.adoc @@ -31,6 +31,8 @@ Supported AsyncAPI versions are: * AsyncAPI 2.6 (JSON) * AsyncAPI 2.6 (YAML) +For gRPC API specifications, Anypoint Code Builder supports Protocol Buffers (Protobuf 3). See xref:des-design-grpc-api-spec.adoc[]. + [[supported-fragment-languages]] == Supported Specification Languages for API Fragments diff --git a/modules/ROOT/pages/des-publish-api-spec-to-exchange.adoc b/modules/ROOT/pages/des-publish-api-spec-to-exchange.adoc index 4a2add67c..8047f861e 100644 --- a/modules/ROOT/pages/des-publish-api-spec-to-exchange.adoc +++ b/modules/ROOT/pages/des-publish-api-spec-to-exchange.adoc @@ -146,5 +146,6 @@ image::des-graphql-asset-exchange.png["GraphQL API spec on Exchange] == See Also +* xref:des-publish-grpc-api-to-exchange.adoc[] * xref:des-govern-api.adoc[] * xref:ai-enabling-api-project-topic-center.adoc[] diff --git a/modules/ROOT/pages/des-publish-grpc-api-to-exchange.adoc b/modules/ROOT/pages/des-publish-grpc-api-to-exchange.adoc new file mode 100644 index 000000000..59acbc3bb --- /dev/null +++ b/modules/ROOT/pages/des-publish-grpc-api-to-exchange.adoc @@ -0,0 +1,71 @@ += Publishing Your gRPC API to Exchange +:page-deployment-options: cloud-ide, desktop-ide + +include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] + +Publish your gRPC API specification or Protobuf library (fragment) to Anypoint Exchange so that other team members can discover, reuse, and implement it. When you publish a gRPC API project, the IDE generates the binary descriptor (`.protobin`) from your `.proto` files so that the published asset is ready for implementation and consumption. + +In Exchange, published gRPC API projects appear as assets of type *gRPC API*. Published Protobuf libraries (reusable fragments) appear as a separate asset type. + +[[prereqs]] +== Before You Begin + +* xref:des-design-grpc-api-spec.adoc[Design a gRPC API specification] in Anypoint Code Builder, or create a Protobuf library project for reusable types and services. +* xref:start-acb.adoc[Set up and access the web or desktop IDE]. +* Have familiarity with xref:access-management::business-groups.adoc[business groups]. When you publish to Exchange from the IDE, you select or confirm the business group for the asset. + +include::partial$acb-reusable-steps.adoc[tags="prereq-business-groups"] + +[[publish-grpc-spec]] +== Publish a gRPC API Project to Exchange + +To publish your gRPC API project (or Protobuf library project) to Exchange: + +. Log in to your Anypoint Platform account. +. In *Explorer*, open your gRPC API project and click the *Publish API Project to Exchange* icon. ++ +image::icon-publish-to-exchange.png["Publish API Project to Exchange icon"] ++ +You can also right-click the API specification and select *Publish API Project to Exchange*. ++ +Alternatively, open the xref:start-use-command-palette.adoc[Command Palette] and run: ++ +[source,command] +---- +MuleSoft: Publish API Project to Exchange +---- +. If prompted, click *Allow* and follow the prompts to sign in to Anypoint Platform. +. Confirm or change each item in *Publish API Project to Exchange*: +* *Asset Version* – For example, `1.0.0` for a first publish. +* *API Version* – Optional for API fragments (Protobuf libraries). +* *Business Group* – The business group where the asset is published. +. Optionally, expand *Project Metadata* and update asset name, tags, categories, or other metadata. Click *Apply* after making changes. +. Optionally, in the banner click *Sync centralized governance rulesets and run validation* to validate the project against applied rulesets. You must be logged in and have a business group defined in the project metadata. ++ +image::des-publish-api-project.png["Publish API Project to Exchange form with banner to sync centralized rulesets"] +. Click *Publish*. ++ +The IDE builds the project and generates the binary descriptor from your Protobuf specification, then publishes the asset to Exchange. When publishing is complete, you see a message that the API specification (or fragment) successfully published to Exchange. ++ +If the project has validation or build errors, fix them before publishing. Check the *Problems* tab and the xref:start-open-output-panel.adoc[output panel] for details. +. Click *View Asset* to open the published asset in Exchange. +. When prompted to implement the API, choose *Yes* to scaffold the gRPC specification into a new project, or *No* to skip. See xref:imp-implement-grpc-api-spec.adoc[] for implementing a gRPC API spec. + +[[locate-grpc-asset]] +== Locate Your gRPC API in Exchange + +After publishing, you can find your gRPC API or Protobuf library in Anypoint Exchange: + +. Log in to Anypoint Platform and open Anypoint Exchange (see xref:des-publish-api-spec-to-exchange.adoc#locate-api[Locate Your API in Exchange] for links). +. Search or browse for the asset by name. gRPC API projects appear as assets of type *gRPC API*. Protobuf library projects appear under the appropriate fragment type. + +Other developers can discover the asset, add it as a dependency for implementation, or import it as a Protobuf library into their gRPC API design projects. + +== See Also + +// TODO: Include a link to gRPC Connector docs. +* xref:des-design-grpc-api-spec.adoc[] +* xref:des-publish-api-spec-to-exchange.adoc[] +* xref:imp-implement-grpc-api-spec.adoc[] +* xref:des-govern-api.adoc[] +* xref:access-management::business-groups.adoc[] diff --git a/modules/ROOT/pages/imp-filter-search-results.adoc b/modules/ROOT/pages/imp-filter-search-results.adoc index 6622534db..50c301b2b 100644 --- a/modules/ROOT/pages/imp-filter-search-results.adoc +++ b/modules/ROOT/pages/imp-filter-search-results.adoc @@ -16,9 +16,9 @@ To search for an API using the search filters: include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::anypoint-code-builder-view.png["Anypoint Code Builder icon highlighted in the activity bar"] -. From *Quick Actions*, click *Implement an API*: +. From *Create*, click *Implement an API*: + -image::implement-api-option-mat.png["Implement an API in the Quick Actions menu"] +image::implement-api-option-mat.png["Implement an API in the Create menu"] . Select *Show Filters* to display the search filters: + image::imp-api-filters.png["Implement API specification screen with the Show filters label highlighted"] @@ -40,6 +40,9 @@ GraphQL enables you to query an API that supports this language in a much more f ** REST APIs + RAML or OAS files that specify APIs referenced by an HTTP Request connector to expose metadata. +** gRPC API ++ +Protocol Buffers (Protobuf) specifications that define gRPC services and methods. Select this type to narrow results when implementing a gRPC API from Exchange. + * Category/Industry + diff --git a/modules/ROOT/pages/imp-implement-grpc-api-spec.adoc b/modules/ROOT/pages/imp-implement-grpc-api-spec.adoc new file mode 100644 index 000000000..275b2f072 --- /dev/null +++ b/modules/ROOT/pages/imp-implement-grpc-api-spec.adoc @@ -0,0 +1,150 @@ += Implementing a gRPC API Specification with Anypoint Code Builder +:page-deployment-options: cloud-ide, desktop-ide + +include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] + +After you design or publish your gRPC API specification, use Anypoint Code Builder to scaffold it into a Mule implementation project. Scaffolding generates the routing logic and a flow for each RPC method defined in your `.proto` file so you can implement and run the gRPC service in a Mule application. + +Anypoint Code Builder uses the service and method definitions in your Protobuf specification to autogenerate an interface that includes: + +* A flow for each RPC method (unary, client streaming, server streaming, or bidirectional streaming) +* A gRPC listener configuration for incoming requests +* Error handlers you can customize + +You can scaffold a gRPC API specification into a new project or into an existing integration project. The process depends on whether the spec is published to Anypoint Exchange or only in a local design project: + +* To scaffold a gRPC spec from Exchange into a new project, see <>. +* To scaffold a gRPC spec from Exchange into an existing project, see <>. +* To scaffold a gRPC spec from a local design project without publishing to Exchange, see <>. +* To update your project with the latest changes to a gRPC spec in Exchange, see <>. + +After scaffolding, implement the business logic in each flow, then run and deploy your Mule app as described in xref:int-developing-integrations.adoc[]. +// TODO: Include a link to gRPC Connector docs. + +== Before You Begin + +* xref:des-design-grpc-api-spec.adoc[Design a gRPC API specification] in Anypoint Code Builder, or have a gRPC API spec already published to Anypoint Exchange as a *gRPC API* asset. The specification must be available in Exchange before you import it into a project. +* xref:start-acb.adoc[Set up and access the IDE]. +* Verify that your Mule runtime supports gRPC. gRPC uses HTTP/2; Mule runtime 4.10 or later is required. See xref:int-versions.adoc[]. + +include::partial$acb-reusable-steps.adoc[tags="prereqs-implementation"] + +[[scaffold-new-grpc-project]] +== Scaffold a gRPC API into a New Project + +If you didn't create a project, use Anypoint Code Builder to scaffold a gRPC API specification from Exchange into a new Mule project: + +include::partial$acb-reusable-steps.adoc[tags="open-ide"] +. From *Create*, click *Implement an API*: +. Complete the *Implement an API Specification* form: ++ +[%header,cols="20a,60a"] +|=== +| Field Name | Field Value + +| *Project Name* | Unique name for your implementation project. + +| *Project Location* | Your home directory or another directory you create. + +See xref:start-add-folders.adoc[]. + +include::partial$acb-reusable-steps.adoc[tags="proj-directory-warn"] +| *Search an API Specification from Exchange* | Name of the gRPC API specification in Exchange. + +Use xref:imp-filter-search-results.adoc[search filters] and select the *Type* that corresponds to gRPC API to narrow results to gRPC specifications. + +| *Mule runtime* | Mule runtime version 4.10 or later (required for gRPC). + +| *Java Version* | Java version compatible with your Mule runtime. + +| *Add to workspace* | Optionally select or deselect to add the new project to the current workspace. Deselect to create the project in the chosen location without opening it in the current workspace. +|=== +. Search for the gRPC API spec, select it, and click *Add Asset* (or equivalent) to add the selected spec to the form. +. Click *Create Project*. ++ +If prompted, trust the authors of the files in the folder. ++ +The scaffolding engine runs and generates the Mule project from the gRPC API specification. A binary descriptor (`.protobin`) is generated from the selected gRPC spec so the project can serve the gRPC service. Once scaffolding completes, Anypoint Code Builder shows a notification such as *Scaffolding finished successfully* and the project reloads. ++ +When you create the project, Anypoint Code Builder: + +* Adds the gRPC API spec as a dependency in your project's `pom.xml` file. +* Adds the Mule and Java versions to the project's `mule-artifact.json` file. +* Scaffolds the gRPC specification into the new Mule project and opens the configuration XML file. + +The configuration XML file includes the interface for your implementation project, with a flow for each RPC method in the spec, a gRPC listener configuration, and error handlers. Add your business logic to each flow and run or deploy the application. + +=== Generate Project Structure + +After scaffolding finishes, the new Mule project contains: + +* *`flows.xml`* (in `src/main/mule/`)–Contains a flow for each RPC method defined in the gRPC service. Each flow includes a gRPC listener source, a logger, and error handlers. Update the logic in these flows to implement your use case. +* *`global-configs.xml`* (in `src/main/mule/`)–Defines the HTTP Listener configuration and the gRPC server configuration (`grpc-server-config`). The gRPC server config references the generated Protobin descriptor so the run-time can serve the gRPC API. +* *`grpc-properties.properties`* (in `src/main/resources/`)–Properties for the gRPC server, such as `grpc.server.host`, `grpc.server.port`, and `grpc.server.descriptorFile`. +* *`src/main/resources/grpc/`*–Folder containing the generated `.protobin` descriptor file used by the gRPC connector at run time. The descriptor is stored in a subfolder organized by the asset's unique ID and version (for example, `src/main/resources/grpc///.protobin`). You can confirm successful generation by opening this folder in the project explorer. +// TODO: Include a link to gRPC Connector docs. + +[[import-grpc-spec-into-project]] +== Import a gRPC API Spec into an Existing Project + +If you xref:int-create-integrations.adoc[created an integration project], you can scaffold a gRPC API specification from Exchange into that project using the same *MuleSoft: Import Asset from Exchange* command. For gRPC API assets, Anypoint Code Builder automatically generates the Protobuf descriptor file (`.protobin`) as part of the import and scaffolding flow. Anypoint Code Builder creates a separate configuration XML file for the gRPC interface in your integration project. + +. In Anypoint Code Builder, open your integration project in the Explorer view. +include::partial$acb-reusable-steps.adoc[tags="open-command-palette"] +include::partial$acb-reusable-steps.adoc[tags="import-api-exchange"] ++ +. From the list of asset types, select *gRPC API*. ++ +image::imp-assets-from-exchange.png["Assets from Exchange dropdown"] +. Select the gRPC API specification to import. +. At the prompt, select the version of the gRPC API spec (for example, `1.0.0`). +. When prompted to scaffold the API dependency, select *Yes*. ++ +When you scaffold the gRPC API dependency, Anypoint Code Builder: + +* Adds the gRPC API spec as a dependency in your project's `pom.xml` file. +* Adds a new configuration XML file for the gRPC interface to the project. + +The new configuration XML file includes flows for each RPC method in the spec, a gRPC listener configuration, and error handlers. Implement the business logic in each flow within the Mule app. + +[[scaffold-local-grpc-spec]] +== Scaffold a Local gRPC API Spec into a New Project + +You can scaffold a gRPC API specification from a local design project without publishing it to Anypoint Exchange. This supports an iterative design-and-implement workflow: you change the `.proto` file in your design project, then re-scaffold to update the implementation project. + +. In Anypoint Code Builder, open your gRPC API design project (the project that contains your `.proto` file). +. In the activity bar or from the project context, use the option to implement or scaffold the local API. +. In the form, specify a name and location for the new implementation project, select the Mule runtime (4.10 or later) and Java version, then confirm. ++ +Anypoint Code Builder scaffolds the gRPC specification into a new Mule project. When the process completes, the IDE opens the configuration XML file with a flow for each RPC method, the gRPC listener configuration, and error handlers. Add your business logic to each flow. + +After you change the `.proto` file, re-scaffold the spec so the implementation project is updated. Use the re-scaffold command or action provided for local API projects in the IDE. + +[[re-scaffold-grpc-spec]] +== Re-scaffold a gRPC API Specification into a Project + +Re-scaffolding updates your implementation or integration project with the latest changes and version of a gRPC API specification in Anypoint Exchange. Re-scaffolding updates the configuration XML and dependencies in your project. + +. In Anypoint Code Builder, open your implementation or integration project in the Explorer view. +include::partial$acb-reusable-steps.adoc[tags="open-command-palette"] +include::partial$acb-reusable-steps.adoc[tags="import-api-exchange"] ++ +. From the list of asset types, select *gRPC API*. ++ +image::imp-assets-from-exchange-multiversion.png["Assets from Exchange dropdown"] +. Select the same gRPC API specification (or the updated asset). +. At the prompt, select the newer version of the gRPC API spec (for example, `2.0.0`). +. When prompted to scaffold the API dependency, select *Yes*. ++ +Anypoint Code Builder updates the project with the new flows and configuration. Review the configuration XML and adjust your business logic as needed. + +== See Also + +// TODO: Include a link to gRPC Connector docs. +* xref:des-design-grpc-api-spec.adoc[] +* xref:des-publish-grpc-api-to-exchange.adoc[] +* xref:imp-implementing-apis.adoc[] +* xref:imp-implement-api-specs.adoc[] +* xref:imp-implement-local-apis.adoc[] +* xref:int-developing-integrations.adoc[] +* xref:int-versions.adoc[] diff --git a/modules/ROOT/pages/imp-implementing-apis.adoc b/modules/ROOT/pages/imp-implementing-apis.adoc index 1f6a19684..c0dff277a 100644 --- a/modules/ROOT/pages/imp-implementing-apis.adoc +++ b/modules/ROOT/pages/imp-implementing-apis.adoc @@ -7,7 +7,7 @@ include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] Use Anypoint Code Builder to start an API implementation by importing and scaffolding an API spec into an interface that you implement and integrate within a Mule app. -Anypoint Code Builder supports automated scaffolding of OAS, RAML, AsyncAPI, and GraphQL APIs, +Anypoint Code Builder supports automated scaffolding of OAS, RAML, AsyncAPI, GraphQL, and gRPC APIs, _except for_ APIs that reference OAS or JSON schema fragment dependencies from Exchange. @@ -16,6 +16,8 @@ The methods for implementing APIs using Anypoint Code Builder are: * xref:imp-implement-api-specs.adoc#scaffold-new-integration[Scaffold an API from a spec in Exchange] and create a new implementation project. [[import-spec-into-project]] * xref:imp-implement-api-specs.adoc#import-spec-into-project[Import an API spec] from Exchange to scaffold the API in an existing integration project. +* xref:imp-implement-grpc-api-spec.adoc[Implement a gRPC API spec] by scaffolding a gRPC (Protobuf) specification from Exchange or a local design project. +// TODO: Include a link to gRPC Connector docs. * xref:imp-implement-local-apis.adoc[Scaffold an API] into an implementation project without first publishing it to Anypoint Exchange, enabling iterative design and implementation. After scaffolding an API specification into an interface, you are ready to develop, test, and deploy your Mule app as described in xref:int-developing-integrations.adoc[]. To understand how an integration project can implement an API specification, see the tutorial xref:tut-af-implement-am-flights-api.adoc[]. diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 3306bbea5..492ba1ea7 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -10,7 +10,7 @@ include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"] //intro Use the Anypoint Code Builder integrated development environment (IDE) for your API designs, implementations, and integration development. Work locally with Anypoint Code Builder for Desktop on Microsoft Visual Studio Code (VS Code) or from your browser with Anypoint Code Builder through Anypoint Platform. The IDEs support the development lifecycle: -* API specification design (OAS or RAML), a mocking service for testing, source control, and publication to Anypoint Exchange +* API specification design, a mocking service for testing, source control, and publication to Anypoint Exchange * API implementation features for importing supported API specifications (such as OAS, RAML, AsyncAPI, or GraphQL) and autogenerating interfaces (scaffolding) for flows and error handlers within a Mule application * Integration development to connect systems, transform data to required formats, and provide business logic to manage messages and events programmatically within a Mule application @@ -57,7 +57,7 @@ See xref:hosting-home::index.adoc[] for more information. == Get Familiar with the Basics -Some knowledge about designing an API using API specification languages (such as OAS, AsyncAPI, or RAML) can be helpful. API implementations and integration development require familiarity with Mule application development, connectors, and the DataWeave transformation language. Anypoint Code Builder xref:tutorials.adoc[] help you get started with these tasks. +Some knowledge about designing an API using API specification languages (such as OAS, RAML, AsyncAPI, or gRPC) can be helpful. API implementations and integration development require familiarity with Mule application development, connectors, and the DataWeave transformation language. Anypoint Code Builder xref:tutorials.adoc[] help you get started with these tasks. It's also useful to be familiar with these products and features: diff --git a/modules/ROOT/pages/int-create-integrations.adoc b/modules/ROOT/pages/int-create-integrations.adoc index 98820b849..e7d6b5147 100644 --- a/modules/ROOT/pages/int-create-integrations.adoc +++ b/modules/ROOT/pages/int-create-integrations.adoc @@ -35,7 +35,7 @@ To create an integration project: // Open the ACB IDE include::partial$acb-reusable-steps.adoc[tags="open-ide"] -. From *Quick Actions*, click *Develop an Integration*: +. From *Create*, click *Develop an Integration*: + image::develop-integration-option-mat.png["Develop an Integration link highlighted in the Getting started section"] . Specify a project name and location in the *Develop an Integration* form. diff --git a/modules/ROOT/pages/ref-acb-commands.adoc b/modules/ROOT/pages/ref-acb-commands.adoc index 21d99775b..5f6fe4565 100644 --- a/modules/ROOT/pages/ref-acb-commands.adoc +++ b/modules/ROOT/pages/ref-acb-commands.adoc @@ -317,7 +317,7 @@ File: Open Folder ---- -* Open the Anypoint Code Builder panel from the IDE. The panel provides links to *Quick Actions*, *Documentation*, and other items. See an example of the panel in xref:start-discover-ui.adoc[]. +* Open the Anypoint Code Builder panel from the IDE. The panel provides links to the most frequent actions. See an example of the panel in xref:start-discover-ui.adoc[]. + [source,command] ---- diff --git a/modules/ROOT/pages/start-discover-ui.adoc b/modules/ROOT/pages/start-discover-ui.adoc index c1aa031ed..577844d44 100644 --- a/modules/ROOT/pages/start-discover-ui.adoc +++ b/modules/ROOT/pages/start-discover-ui.adoc @@ -26,7 +26,7 @@ In addition to Anypoint Code Builder (MuleSoft icon), commonly used items in the You can change the order of the items in your activity bar. . *Anypoint Code Builder* (MuleSoft icon): Open the *Anypoint Code Builder* panel to start a project. Follow the tutorials to get started with API specification design, implementation, and integration development in Anypoint Code Builder. -. *Quick Actions*: Start an API specification, implementation, or integration project. +. *Create*: Start an API specification, implementation, or integration project. . *Settings*: Set Anypoint Code Builder configurations, including the xref:index.adoc#us-eu-clouds[US or EU cloud] for your IDE. Select the cloud where your Anypoint Platform user account resides. == Compare Project UIs in the IDE diff --git a/modules/ROOT/pages/start-workspaces.adoc b/modules/ROOT/pages/start-workspaces.adoc index 69397d8da..ee207a7b0 100644 --- a/modules/ROOT/pages/start-workspaces.adoc +++ b/modules/ROOT/pages/start-workspaces.adoc @@ -24,7 +24,7 @@ To create a project in a workspace: . Start the project creation process using one of the following methods: + -** From the *Quick Actions* menu, select the project type. +** From the *Create* menu, select the project type. + For example, *Design an API* or *Develop an Integration*. ** From the Command Palette, run the appropriate command. diff --git a/modules/ROOT/pages/tut-af-design-am-flights-api.adoc b/modules/ROOT/pages/tut-af-design-am-flights-api.adoc index 7cad477d7..feaf6553c 100644 --- a/modules/ROOT/pages/tut-af-design-am-flights-api.adoc +++ b/modules/ROOT/pages/tut-af-design-am-flights-api.adoc @@ -31,7 +31,7 @@ Start creating the American Flights API specification: include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::acb-mulesoft-in-activity-bar.png["MuleSoft icon in the VS Code Activity Bar"] -. From *Quick Actions*, click *Design an API*: +. From *Create*, click *Design an API*: + image::design-api-1.png["Link to Design an API in the MuleSoft panel"] + diff --git a/modules/ROOT/pages/tut-af-integrate-am-flights.adoc b/modules/ROOT/pages/tut-af-integrate-am-flights.adoc index fa9c5f605..1b901e7dc 100644 --- a/modules/ROOT/pages/tut-af-integrate-am-flights.adoc +++ b/modules/ROOT/pages/tut-af-integrate-am-flights.adoc @@ -23,7 +23,7 @@ Start an integration application for the American Flights example. include::partial$acb-reusable-steps.adoc[tags="open-ide"] + image::acb-mulesoft-in-activity-bar.png["MuleSoft icon in the VS Code Activity Bar"] -. From *Quick Actions*, click *Develop an Integration*: +. From *Create*, click *Develop an Integration*: + image::develop-integration-option-mat.png["Develop an Integration link highlighted in the Getting started section"] . Provide integration project properties to the *Develop an Integration* form: diff --git a/modules/ROOT/pages/vibes-create-integrations.adoc b/modules/ROOT/pages/vibes-create-integrations.adoc index 81b6716f8..3079e086b 100644 --- a/modules/ROOT/pages/vibes-create-integrations.adoc +++ b/modules/ROOT/pages/vibes-create-integrations.adoc @@ -34,7 +34,7 @@ image::int-einstein-icon-in-toolbar.png["Arrow pointing to the Mulesoft Vibes ic To create a new integration development project: include::partial$acb-reusable-steps.adoc[tags="open-ide"] -. From *Quick Actions*, click *Develop an Integration*: +. From *Create*, click *Develop an Integration*: + image::develop-integration-option-mat.png["Develop an Integration link highlighted in the Getting started section"]