Contact Us 1-800-596-4880
  1. Homepage
  2. Anypoint Code Builder
  3. Designing API Specs and Fragments

  4. Designing a gRPC API Specification with Anypoint Code Builder

Designing a gRPC API Specification with Anypoint Code Builder

logo cloud IDE Cloud IDE

logo desktop IDE Desktop IDE

Open Beta Release: The cloud IDE is in open beta. Any use of Anypoint Code Builder in its beta state is subject to the applicable beta services terms and conditions, available from the IDE.

Anypoint Code Builder supports designing gRPC API specifications using Protocol Buffers 3 (Protobuf 3). Create and edit .proto files, import reusable Protobuf libraries from Anypoint Exchange, and use syntax highlighting and validation. 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

Create a New gRPC API Specification Project

To create a gRPC API spec project in Anypoint Code Builder:

  1. In the activity bar of the IDE, click the (Anypoint Code Builder) icon.

  2. From Create, click Design an API:

  3. Complete the API Specification form:

    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.

    To reuse an existing project name, you must delete the project that is already using the name first. See Deleting API Specs and Fragments.

    Project Location

    Your home directory or another directory you create.

    See Adding Folders to Your Home Directory.

    Don’t create the project within another project directory.

    API Type

    The type of API spec to create.

    Select gRPC API to create a gRPC project.

    API Specification Language

    The language for the API specification.

    Select Protobuf 3 for gRPC API projects.

  4. 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.

  5. Continue designing your gRPC API spec.

    As you enter elements, use 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.

Edit the main .proto file to define service, rpc, and message blocks. To reuse shared types, add new .proto files in the same project and import them. You can also add a Protobuf fragment as a dependency from Exchange and import it in your specification.

Publish a gRPC Fragment to Exchange

Publish reusable .proto definitions as a fragment to Anypoint Exchange so other gRPC API specifications can import them as dependencies.

A fragment contains shared definitions such as message or enum blocks.

Publish the Fragment

To publish a gRPC fragment to Exchange:

  1. Ensure that you’re logged in to Anypoint Platform.

  2. Open the project that contains your reusable .proto files.

  3. From the IDE, select the publish action.

  4. When prompted:

    • Select the business group.

    • Provide the asset name and version.

    • Add any required metadata.

  5. Confirm the publication.

After publishing, the fragment appears in Exchange as an API Fragment asset and can be added as a dependency to other gRPC API specification projects.

To use the fragment in another gRPC API specification:

  1. Add the fragment as a dependency from Exchange.

  2. Import the corresponding .proto file in your main specification.

  3. Validate that all references resolve correctly.

Import a Protobuf Library from Anypoint Exchange

Import reusable Protobuf libraries (fragments) from Anypoint Exchange and add them as dependencies to your gRPC API project. You can reuse messages and services across multiple specifications.

To use a Protobuf fragment published to Exchange:

  1. Ensure you’re logged in to Anypoint Platform.

  2. Open your gRPC API project.

  3. Open the Command Palette (Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows).

  4. Select MuleSoft: Add Fragment dependency from Exchange.

  5. Search for the Protobuf fragment you need and select the version to add.

  6. After the dependency is added, the library is available under the project.

  7. In your main .proto file, use import to reference the library’s package and message or service definitions. For example:

    syntax = "proto3";

import "path/to/library.proto";

service MyService {
  rpc GetOrder(OrderRequest) returns (OrderResponse);
}

  8. 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

Specify RPC communication patterns in your service definitions and use built-in validation to verify your Protobuf specification.

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 output panel to track validation and scaffolding status.

See Also