> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# gRPC API Proxy Creation

> You can manage and securely expose your gRPC services through the Apinizer platform. You can use the high-performance RPC framework developed by Google, work with Protocol Buffers (protobuf) format. You can create gRPC API Proxy from protobuf file, import proto file, define services and methods, and configure routing

<CardGroup cols={2}>
  <Card title="Protobuf Format" icon="file-code">
    gRPC API Proxy performs message processing in Protocol Buffers (protobuf) format. This format is more compact and faster than JSON.
  </Card>

  <Card title="HTTP/2 Protocol" icon="network-wired">
    gRPC runs on HTTP/2 protocol and provides multiplexing support.
  </Card>

  <Card title="Streaming Support" icon="stream">
    Supports Unary, Server Streaming, Client Streaming, and Bidirectional Streaming methods.
  </Card>

  <Card title="High Performance" icon="gauge">
    Provides higher performance than JSON thanks to binary protobuf format.
  </Card>
</CardGroup>

## gRPC API Proxy Creation Methods

There are several methods to create a gRPC API Proxy:

<AccordionGroup>
  <Accordion title="Import from Protobuf (.proto) File">
    The most common method is to import from a protobuf (.proto) file. This method automatically imports your services, methods, and message types.
  </Accordion>

  <Accordion title="Manual Creation">
    You can also manually create a gRPC API Proxy without a protobuf file. In this case, you need to manually define services and methods.
  </Accordion>

  <Accordion title="Copy from Existing API Proxy">
    You can create a new proxy by copying an existing gRPC API Proxy. This method saves time for similar services.
  </Accordion>
</AccordionGroup>

## Import from Protobuf File

<Steps>
  <Step title="Go to API Proxy Creation Page">
    **Development → API Proxies** item is selected in the main menu on the left. The **+Create** button at the top right of the opened interface is clicked and **gRPC API** option is selected.
  </Step>

  <Step title="Upload Protobuf File">
    There are three methods to upload a protobuf file:

    <AccordionGroup>
      <Accordion title="Method 1: File Upload">
        The **Upload File** button is clicked. A `.proto` file is selected from your computer. The file is automatically parsed and service information is displayed.

        <Info>
          **Protobuf File Format** A protobuf file is a file that defines your gRPC services. The file contains definitions such as `service`, `rpc`, `message`.
        </Info>
      </Accordion>

      <Accordion title="Method 2: Load from URL">
        The **Enter URL** link is clicked. The URL of the protobuf file is entered and the **Parse** button is clicked. The file is parsed and service information is displayed.

        <Info>
          **Authentication and SSL** If the spec URL requires authentication, enable **Use Spec Authorization** to enter custom headers or **Basic Auth** (username/password). In the **SSL / Certificate Settings** panel, configure **Connection Timeout**, **Customize SSL/TLS Settings**, **Skip SSL Verification**, and **Server Certificate Verification** (System Default, TrustStore, or PEM) for HTTPS access. For details, see [API Proxy Creation](/en/develop/api-proxy-creation/api-proxy-creation).
        </Info>
      </Accordion>

      <Accordion title="Method 3: Paste as Text">
        The **Paste as Text** option is selected. The protobuf content is pasted into the text field and the **Parse** button is clicked. The content is parsed and service information is displayed.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Check Service Information">
    After the parse operation is completed, the following information is displayed:

    <CardGroup cols={2}>
      <Card title="Package" icon="tag">
        Protobuf package name
      </Card>

      <Card title="Services" icon="network-wired">
        All gRPC services
      </Card>

      <Card title="Methods" icon="list">
        RPC methods for each service
      </Card>

      <Card title="Message Types" icon="file-code">
        Request and response message types
      </Card>

      <Card title="Streaming Type" icon="stream">
        Unary, Server Streaming, Client Streaming, or Bidirectional Streaming
      </Card>
    </CardGroup>
  </Step>

  <Step title="Routing Configuration">
    <AccordionGroup>
      <Accordion title="Client Route (Relative Path)">
        Client Route is the endpoint where the API Proxy is exposed to the outside world. Clients access the gRPC service through this endpoint.

        **Example:**

        ```
        Relative Path: /grpc/user-service
        ```

        In this case, the gRPC service is accessed as follows:

        ```
        {apinizer-gateway}/grpc/user-service
        ```
      </Accordion>

      <Accordion title="Upstream Target (Backend Address)">
        Upstream Target is the address of your backend gRPC service. The API Proxy routes requests to this address.

        **Configuration Format:**

        ```
        host:port
        ```

        **Example:**

        ```
        backend-grpc.example.com:50051
        ```

        <Info>
          **gRPC Port** gRPC services usually run on special ports like 50051. Make sure you correctly specify the port number of your backend service.
        </Info>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="gRPC Routing Configuration">
    Special routing configuration can be made for gRPC. For more information, you can refer to the [gRPC Routing](/en/develop/routing/grpc-routing) page.
  </Step>

  <Step title="Save API Proxy">
    All information is checked. The **Relative Path** field is filled (required). **Upstream Target** information is entered (in host:port format). The **Save** button at the top right is clicked.
  </Step>
</Steps>

<Check>
  gRPC API Proxy created successfully!
</Check>

## Protobuf File Structure

A protobuf file generally has the following structure:

```protobuf theme={null}
syntax = "proto3";

package com.example.service;

// Message definitions
message UserRequest {
  string user_id = 1;
}

message UserResponse {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

// Service definition
service UserService {
  // Unary RPC
  rpc GetUser(UserRequest) returns (UserResponse);
  
  // Server Streaming RPC
  rpc ListUsers(UserRequest) returns (stream UserResponse);
  
  // Client Streaming RPC
  rpc CreateUsers(stream UserRequest) returns (UserResponse);
  
  // Bidirectional Streaming RPC
  rpc ChatUsers(stream UserRequest) returns (stream UserResponse);
}
```

## gRPC Method Types

gRPC supports four different method types:

<CardGroup cols={2}>
  <Card title="Unary RPC" icon="arrow-right">
    Single request, single response. The most commonly used method type.

    **Example:**

    ```protobuf theme={null}
    rpc GetUser(UserRequest) returns (UserResponse);
    ```
  </Card>

  <Card title="Server Streaming RPC" icon="arrow-down">
    Single request, multiple responses. Server sends a stream.

    **Example:**

    ```protobuf theme={null}
    rpc ListUsers(UserRequest) returns (stream UserResponse);
    ```
  </Card>

  <Card title="Client Streaming RPC" icon="arrow-up">
    Multiple requests, single response. Client sends a stream.

    **Example:**

    ```protobuf theme={null}
    rpc CreateUsers(stream UserRequest) returns (UserResponse);
    ```
  </Card>

  <Card title="Bidirectional Streaming RPC" icon="arrows-rotate">
    Multiple requests, multiple responses. Both sides send streams.

    **Example:**

    ```protobuf theme={null}
    rpc ChatUsers(stream UserRequest) returns (stream UserResponse);
    ```
  </Card>
</CardGroup>

## Post-Import Configuration

After the API Proxy is created, the following configurations can be made:

<CardGroup cols={2}>
  <Card title="gRPC Routing Configuration" icon="route" href="/en/develop/routing/grpc-routing">
    gRPC Routing determines how methods will be routed.
  </Card>

  <Card title="Adding Policies" icon="shield" href="/en/develop/api-proxy-configuration/policy-management">
    Policies such as security, validation, transformation can be added to the API Proxy.

    <Tip>
      Some policies can be specifically applied for gRPC. For example, policies for validating or transforming protobuf messages.
    </Tip>
  </Card>

  <Card title="Testing" icon="flask" href="/en/develop/test-debug-tools/test-console">
    gRPC API Proxy can be tested. Apinizer Test Console provides gRPC test support.
  </Card>

  <Card title="Deployment and Version" icon="rocket" href="/en/develop/deployment-and-version-management">
    API Proxy can be deployed to environment(s).
  </Card>
</CardGroup>

## Common Scenarios

<AccordionGroup>
  <Accordion title="Scenario 1: Exposing Internal gRPC Service">
    To expose an internal gRPC service to the outside world:

    <Steps>
      <Step title="Upload Proto File">
        The `.proto` file of your gRPC service is uploaded.
      </Step>

      <Step title="Determine Relative Path">
        Relative Path is determined (for example: `/grpc/user-service`).
      </Step>

      <Step title="Set Upstream Target">
        The address of the internal service is used as Upstream Target (for example: `internal-grpc.example.com:50051`).
      </Step>

      <Step title="Add Security Policies">
        Security policies such as mTLS, Authentication are added.
      </Step>

      <Step title="Save and Deploy">
        API Proxy is saved and deployed.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Scenario 2: gRPC Service Versioning">
    To create separate API Proxies for different versions:

    <Steps>
      <Step title="Separate Proto File for Each Version">
        A separate `.proto` file is used for each version.
      </Step>

      <Step title="Different Relative Paths">
        Different Relative Paths are used (for example: `/grpc/v1/user-service`, `/grpc/v2/user-service`).
      </Step>

      <Step title="Separate Policies">
        Separate policies are defined for each version.
      </Step>

      <Step title="Migration Strategy">
        Migration strategy between versions is determined.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Scenario 3: Converting gRPC to REST">
    To expose a gRPC service as a REST API:

    <Steps>
      <Step title="Create gRPC API Proxy">
        A gRPC API Proxy is created.
      </Step>

      <Step title="REST Transformation Policies">
        REST transformation policies are added.
      </Step>

      <Step title="Map Methods">
        gRPC methods are mapped to REST endpoints.
      </Step>

      <Step title="Configure Transformations">
        Request/Response transformations are configured.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Protobuf File Quality" icon="file-code">
    Make sure your protobuf file is valid and up-to-date. Invalid files may cause errors during import.
  </Card>

  <Card title="Relative Path Strategy" icon="route">
    Use a consistent naming convention for Relative Paths. For example: `/grpc/{service-name}/{version}`
  </Card>

  <Card title="Backend Address" icon="server">
    Define backend addresses as environment variables. This provides flexibility for different environments.
  </Card>

  <Card title="mTLS Security" icon="shield">
    Always use mTLS (mutual TLS) security for gRPC. gRPC services usually run on internal networks and security is critical.
  </Card>

  <Card title="Streaming Performance" icon="stream">
    Optimize performance for streaming methods. Optimize buffer settings for large data streams.
  </Card>

  <Card title="Error Handling" icon="circle-exclamation">
    Handle gRPC error codes (status codes) correctly. gRPC uses a different error system than HTTP status codes.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Import Error">
    **Problem:** Protobuf file cannot be imported.

    **Solution:**

    * Make sure the protobuf file has valid syntax (proto2 or proto3).
    * Make sure all dependencies of the file (imported files) are present.
    * Check URL accessibility.
    * Make sure the file size is within the limit.
  </Accordion>

  <Accordion title="Services Not Visible">
    **Problem:** Services are not visible after import.

    **Solution:**

    * Make sure `service` definitions in the protobuf file are correct.
    * Check that the package name is correctly defined.
    * Check that RPC methods are correctly defined.
  </Accordion>

  <Accordion title="Routing Error">
    **Problem:** Requests are not routed to backend.

    **Solution:**

    * Make sure the Upstream Target address is in the correct format (host:port).
    * Check that your backend gRPC service is accessible.
    * Check gRPC Routing configuration.
    * Make sure the port number is correct.
  </Accordion>

  <Accordion title="Streaming Error">
    **Problem:** Streaming methods are not working.

    **Solution:**

    * Check that streaming methods are correctly defined.
    * Make sure HTTP/2 support is active.
    * Check timeout settings (longer timeout may be required for streaming).
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="gRPC Routing" icon="route" href="/en/develop/routing/grpc-routing">
    Learn gRPC Routing configuration
  </Card>

  <Card title="Policy Management" icon="shield" href="/en/develop/api-proxy-configuration/policy-management">
    Learn to add policies
  </Card>

  <Card title="mTLS Security" icon="lock" href="/en/develop/policies/mtls-authentication">
    Learn about mTLS security
  </Card>

  <Card title="Deployment and Version" icon="rocket" href="/en/develop/deployment-and-version-management">
    Learn to deploy
  </Card>
</CardGroup>