Creating a gRPC API
APIG supports gRPC API creation. gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. You only need to define the request and response of each API, and let the gRPC framework take care of the rest. gRPC uses protocol buffers (protobuf) as its Interface Definition Language (IDL) and for bottom-layer message exchange. The following table compares gRPC and REST APIs.
Parameter |
gRPC |
REST |
---|---|---|
Message encoding |
protobuf |
JSON |
Transmission protocol |
HTTP/2 |
HTTP |
Transmission performance |
Fast, with less content to transmit |
More content to transmit |
Transmission mode |
Send a single request and receive a single response. |
If both your client and server are of the gRPC type, you can create an gRPC API to open up your backend capabilities. gRPC features low resource consumption and high transmission rate. It is suitable for internal service invocation and governance.
Constraints
- gRPC APIs cannot be imported, exported, or debugged, and do not support the import of API design files, CSE microservices, or CCE workloads.
- Circuit breaker policies whose backend policy type is Mock, HTTP&HTTPS, or FunctionGraph are not supported.
- Base64 encoding is not supported.
- Parameter orchestration is not supported.
Prerequisites
- You have created an API group. If no API group is available, create one by referring to Creating an API Group.
- If the backend service needs to use a load balance channel, create a channel first.
- The backend service has a proto file that defines API request and response parameters. The proto file is used in gRPC to define data structures and service APIs. It describes data structures and interactions using protobuf and serves as a contract for communication between the client and backend services.
Creating a gRPC API
- Go to the APIG console.
- Select a gateway at the top of the navigation pane.
- In the navigation pane, choose API Management > API Groups.
- Click a group name to go to the Group Information page.
- On the APIs tab page, choose Create API > Create gRPC API.
- Configure the frontend parameters described in the following table.
The new API must have a different group, request method, request path, and matching mode from those of any existing API.
Table 2 Frontend definition Parameter
Description
API Name
Enter an API name that conforms to specific rules to facilitate search.
Enter 3 to 255 characters, starting with a letter or digit. Use only letters, digits, and these special characters: -_./:()
Group
The group to which the API belongs. To create a group, click Create API Group.
URL
Frontend address, which consists of a method, protocol, subdomain name, and path.
- Method: defaults to POST.
- Protocol: defaults to GRPCS.
- Subdomain Name: Debugging domain name of the group to which the API belongs.
- Path: Set the path to any of the following:
- /
- /{Package name}.{Service name}
- /{Package name}.{Service name}/{Method name}
NOTE:
- Obtain the package name, service name, and method name from the proto file.
- Absolute match can be used only when the frontend path is set to /{Package name}.{Service name}/{Method name}.
Gateway Response
Displayed if an API request fails to be processed.
APIG provides a set of default responses and also allows you to create new ones with custom status codes and content on the Group Information page. The response content must be in JSON format.
Matching
Matching mode of the API request path.
- Exact match: The path in a request for the API must be the same as the value of Path.
- Prefix match: The path in a request for the API must be prefixed with the value of Path. You can define multiple paths in this mode.
For example, if you set Path to /test/AA and Matching to Prefix match, the API can be called using /test/AA/BB and /test/AA/CC but cannot be called using /test/AACC.
NOTE:
- If you set the matching mode to Prefix match, the characters of the API request path excluding the prefix are transparently transmitted to the backend.
For example, if you define the frontend and backend request paths of an API as /test/ and /test2/, respectively, and the API is called using /test/AA/CC, the characters AA/CC will be transparently transmitted to the backend. The request URL received by the backend is /test2/AA/CC/.
- In prefix match mode, the path in a request preferentially matches the API with the longest path.
For example, assume that prefix match is enabled for two APIs whose paths are /test/AA and /test/AA/BB, respectively. The path /test/AA/BB/c in a request matches the API whose path is /test/AA/BB.
- If there are two APIs with the same group, request method, and request path, the API with exact matching is first called.
Tags
Attributes used to quickly identify the API from other APIs.
The value can contain 1 to 128 characters, including letters, digits, and the following special characters: _-*#%.:. It must start with a letter. Separate multiple tags with commas (,).
Description
API description, which contains 1 to 1,000 characters.
Request Body Content
Enter the content of the request body in the API request to help API callers understand how to correctly encapsulate API requests.
- Configure security settings based on the following table.
Table 3 Security configuration Parameter
Description
Type
Determine whether the API is available to the public. Options:
- Public: The API can be released to KooGallery.
- Private: The API will be excluded when the API group to which it belongs is released on KooGallery.
Authentication Mode
The following authentication modes are available:
- App: Requests will be authenticated by APIG. This authentication mode is recommended.
- IAM: Requests will be authenticated by IAM.
- Custom: Requests for the API will be authenticated by using your own authentication system or service (for example, an OAuth-based authentication system).
- None: No authentication will be required. To call APIs that do not require authentication, construct standard HTTP requests and send them to APIG.
APIG transparently transmits requests to call an API that does not require authentication to the backend service. If you want requests to be authenticated on the API backend service, you can set Security Authentication to None. The API caller transfers the fields required for authentication to the backend service, and the backend service performs authentication.
API calling varies depending on the authentication mode. For details, see Calling an Open API.
NOTICE:- If you set the authentication mode of an API to IAM, any APIG user can access the API, which can result in excessive charges if the API is bombarded with malicious requests.
- If you set the authentication mode of an API to None, any user can access the API over public networks, which can result in excessive charges if the API is bombarded with malicious requests.
- If you set the authentication mode to Custom, you can create a function in FunctionGraph to interconnect with your own authentication system or service. Ensure that FunctionGraph is available in the current region.
Simple Authentication
This parameter is available only if you set Security Authentication to App.
If you select app authentication, configure whether to enable simple authentication. In simple authentication, the X-Apig-AppCode parameter is added to the gRPCS request header for quick response. APIG verifies only the AppCode and the request content does not need to be signed.
Simple authentication only supports gRPCS requests and does not support gRPC requests. For details, see Configuring AppCodes for Simple Authentication.
NOTE:
After you enable simple authentication for an existing API, you need to publish the API again. For details, see Publishing an API.
Two-Factor Authentication
This parameter is available only if Authentication Mode is set to App or IAM.
This parameter specifies whether to perform two-way authentication on API calling. If this parameter is selected, the custom function API is also used to authenticate API requests when APP or IAM has been selected for Security Authentication.
Custom Authorizer
This parameter is mandatory only if Authentication Mode is set to Custom.
Select a frontend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a frontend custom authorizer.
CORS
Determine whether to enable cross-origin resource sharing (CORS).
CORS allows browsers to send XMLHttpRequest to servers in other domains, overcoming the limitation that Asynchronous JavaScript and XML (AJAX) can be used only within the same domain.
There are two types of CORS requests:
- Simple requests: requests that have the Origin field in the header.
- Not-so-simple requests: gRPC requests sent before the actual request.
If CORS (not-so-simple request) is enabled for an API, another API that uses the OPTIONS method must be created. For details, see Enabling CORS.
- Configure the frontend parameters described in the following table.
- Click Next and configure the backend service.
- Define the default backend.
API requests that do not meet the conditions of any backend will be forwarded to the default backend.
On the Backend Configuration page, select a backend type.
Backend types include Table 4 and Table 5.
NOTE:
FunctionGraph backends can be set only if FunctionGraph has been deployed in the current environment.
gRPC APIs with a FunctionGraph backend are supported in CN Southwest-Guiyang1, CN East-Shanghai1, CN North-Beijing4, CN East-Shanghai2, and LA-Santiago.
Table 4 Parameters for defining a gRPC&gRPCS backend service Parameter
Description
Load Balance Channel
Determine whether to use a load balance channel to access backend services.
URL
A URL consists of a method, protocol, load balance channel/backend address, and path.
- Method
The default value is POST.
- Protocol
GRPC or GRPCS. This protocol must be the one used by the backend service.
- Load Balance Channel
Set this parameter only if a load balance channel is used. Select an existing load balance channel or create one.
To ensure a successful health check and service availability, configure the security groups of cloud servers in each channel to allow access from 100.125.0.0/16.
- Backend Address
Set this parameter if no load balance channel is used.
Enter the access address of the backend service in the format of Host:Port. Host indicates the IP address or domain name for accessing the backend service. Port is the port of the backend service. If no port is specified, port 80 is used for gRPC by default, and port 443 is used for gRPCS by default.
To use environment variables in the backend address, enclose the variables with number signs (#), for example, #ipaddress#. You can use multiple environment variables, for example, #ipaddress##test#.
NOTE:
If you have enabled public outbound access for a gateway, the IP address or domain name can be a public IP address (ECS EIP, public IP address of your own server, or ELB address), a public domain name, or a private network IP address. Private domain names cannot be used.
Gateways created after October 30, 2022 can transmit server name indication (SNI) to backend services during TLS handshake.
- Path
The request path (URI) of the backend service. Ensure that any parameters in the path are enclosed in braces ({}). For example, /getUserInfo/{userId}.
If the path contains an environment variable, enclose the environment variable in number signs (#), for example, /#path#. You can use multiple environment variables, for example, /#path##request#.
NOTE:
- APIs whose URLs contain variables cannot be debugged on the API debugging page.
- For variables defined in URLs of APIs, corresponding environment variables and their values must be configured. Otherwise, the APIs cannot be published because there will be no values that can be assigned to the variables.
- The variable name is case-sensitive.
Host Header
Set this parameter only if a load balance channel is used.
Host header field in the backend service request. By default, the original host header in each request is used.
Timeout (ms)
Backend request timeout. Range: 1–60,000 ms.
- If a backend timeout error occurs during API debugging, increase the timeout to locate the reason.
- If the current timeout does not meet your service requirements, modify the maximum timeout by referring to Configuring Gateway Parameters. The value range is 1 ms to 600,000 ms. After modifying the maximum timeout, also modify the timeout here.
Retries
Number of attempts to retry requesting the backend service. Default: 0; range: –1 to 10.
- If the value is –1, the retry function is disabled. However, requests except for those using POST and PATCH will be retried once by default.
- If the value is within 0 to 10, the retry function is enabled, and requests will retry for the specified number of times. 0 indicates no retry attempts will be made.
If a load balance channel is used, the number of retries must be less than the number of enabled backend servers in the channel.
Two-Way Authentication
Set this parameter only when Protocol is set to GRPCS.
Determine whether to enable two-way authentication between APIG and the backend service. If you enable this option, configure the backend_client_certificate parameter when Configuring Gateway Parameters.
Backend Authentication
Determine whether your backend service needs to authenticate API requests.
If you enable this option, select a custom authorizer for backend authentication. Custom authorizers are functions that are created in FunctionGraph to implement an authentication logic or to invoke an authentication service.
NOTE:
Backend authentication relies on FunctionGraph and is only available in certain regions.
Table 5 Parameters for defining a FunctionGraph backend service Parameter
Description
Function Name
Automatically displayed when you select a function.
Function URN
Identifier of the function.
Click Select to specify a function.
Version/Alias
Select a version or alias for your function. For details, see Version Management or Alias Management.
Invocation Mode
Default: Synchronous. When receiving an invocation request, FunctionGraph immediately processes the request and returns a result. The client closes the connection once it has received a response from the backend.
Timeout (ms)
Backend request timeout. Range: 1–60,000 ms.
- If a backend timeout error occurs during API debugging, increase the timeout to locate the reason.
- If the current timeout does not meet your service requirements, modify the maximum timeout by referring to Configuring Gateway Parameters. The value range is 1 ms to 600,000 ms. After modifying the maximum timeout, also modify the timeout here.
Backend Authentication
Determine whether your backend service needs to authenticate API requests.
If you enable this option, select a custom authorizer for backend authentication. Custom authorizers are functions that are created in FunctionGraph to implement an authentication logic or to invoke an authentication service.
NOTE:
Backend authentication relies on FunctionGraph and is only available in certain regions.
- Method
- (Optional) Add a backend policy.
You can add backend policies to forward requests to different backend services.
- Click
to add a backend policy.
- Set policy parameters described in Table 6. For details about other parameters, see Table 4 and Table 5.
Table 6 Backend policy parameters Parameter
Description
Name
The backend policy name.
Start with a letter, and use letters, digits, hyphens (-), and underscores (_). (3 to 64 characters)
Effective Mode
Select the effective mode of the backend policy.
- Any condition met: The backend policy takes effect if any of the policy conditions has been met.
- All conditions met: The backend policy takes effect only when all the policy conditions have been met.
Policy Conditions
Conditions that must be met for the backend policy to take effect. Set conditions by referring to Table 7.
Table 7 Policy Conditions Parameter
Description
Source
Source of the conditions specified in the policy
- Source IP address: IP address from which the API is called
- Request parameter: a request parameter defined for the API
- Cookie: cookies of an API request
- System parameter: a default gateway parameter used to define system runtime for the API
NOTICE:- The request parameters (for example, headers) set as policy conditions must have already been defined for the API.
- If System parameter is not displayed, contact technical support to upgrade the gateway.
Parameter Name
- When setting Source to Request parameter, select a request parameter.
- When setting Source to System parameter, select a system parameter.
- reqPath: Request URI, for example, /a/b/c.
- reqMethod: Request method, for example, GET.
- When setting Source to Cookie, enter the name of a cookie parameter.
Parameter Location
The parameter location is displayed only if you set Source to Request parameter.
Condition Type
This parameter is mandatory only if you set Source to Request parameter, Cookie, or System parameter.
- Equal: The request parameter must be equal to the specified value.
- Enumerated: The request parameter must be equal to any of the enumerated values.
- Matching: The request parameter must be equal to any value of the regular expression.
NOTE:
When you set Source to System parameter and select a parameter named reqMethod, you can set the condition type only to Equal or Enumerated.
Condition Value
Enter the condition value. The value contains 1 to 1,024 characters.
- If Condition Type is Equal, enter a value.
- If Condition Type is Enumerated, enter multiple values and separate them with commas (,).
- If Condition Type is Matching, enter a value range, for example, [0-5].
- If Source is Source IP address, enter one or more IP addresses and separate them with commas (,).
- If Source is System parameter - Frontend authentication parameter and the condition value is of the Boolean type, the parameter must be in lowercase.
- Click
- Click Finish. You can view the API details on the APIs tab that is displayed.
Related Documents
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot