MPC API - Mobile Platform as a Service - Alibaba Cloud Documentation Center

The Quick Start guides you to register and publish an MPC API service to be called by mobile client within 10 minutes. The procedure falls into 6 steps:

Server development
Register API group
Register API service
Configure API service
Test API service
Generate client SDK

Server development

Introduce the second-party package of gateway

Introduce the following second-party package (ignore it if the original project has had dependency) in the main pom.xml file of the project. In which the mobilegw-unify dependencies must be the latest version 1.0.5.20200930.

<!-- mobilegw unify dependency-->
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-mpc</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-spi-adapter</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.gateway</groupId>
    <artifactId>mobilegw-unify-log</artifactId>
    <version>${the-lastest-version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.hybirdpb</groupId>
    <artifactId>classparser</artifactId>
    <version>1.2.2</version>
</dependency>
<dependency>
    <groupId>com.alipay.mpaaschannel</groupId>
    <artifactId>common</artifactId>
    <version>2.3.2018071001</version>
</dependency>
<dependency>
    <groupId>com.alipay.mpaaschannel</groupId>
    <artifactId>tenant-client</artifactId>
    <version>2.3.2018071001</version>
</dependency>
<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.5</version>
</dependency>
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.69_noneautotype</version>
</dependency>
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>hessian</artifactId>
    <version>3.3.6</version>
</dependency>

Define and implement the service interface

Define the service interface com.alipay.xxxx.MockRpc based on business requirement.
Notes:
- Try to define the incoming parameter in the method as VO. In this way, if you want to add any parameter later, you can add the parameters in the VO without changing the method declaration format.
- For relevant specifications about service interface definition, see Business interface definition specifications.
Provide the implementation of the interface: com.alipay.xxxx.MockRpcImpl.

Define OperationType

Add @OperationType annotation to the service interface’s method to define the interface that is to publish services. @OperationType contains three parameters. For convenient maintenance, ensure that all 3 parameters are completely entered:

value: The unique identifier of RPC service. value must be globally unique in the gateway, you need to define it as much as possible. Otherwise, it might be the same as the value of other business party, which might lead service registration failure. The definition rule is organization.product domain.product.sub-product.operation.
name: Interface name.
desc: Interface description.

Code sample:

public interface MockRpc {

    @OperationType(value="com.alipay.mock", name="MPC mock interface", desc="Complex mock interface")
    Resp mock(Req s);

    @OperationType(value="com.alipay.mock2", name="xxx", desc="xxx")
    String mock2(String s);
}

public static class Resp {
    private String msg;
    private int    code;

    // ignore getter & setter
}

public static class Req {
    private String name;
    private int age;

    // ignore getter & setter
}

Declare API service

In this step, the pre-defined RPC service is declared as the API (that provides services) through the SPI package provided by the gateway. The following 5 parameters are required:

registryUrl: It refers to the address of the registration center. For the shared Ant Financial Cloud registration center, the address is mpcpub.mpaas.cn-hangzhou.aliyuncs.com.
appName: It refers to the business-side application name.
workspaceId: It refers to the workspaceId of the workspace where the application is.
projectName: It refers to the project name of the tenant where the application is.
privateKeyPath: The ClassPath used to store RSA key, which is used to verify the legality when the gateway establishes connection with mpaaschannel.
- Note: This private key corresponds to the App public key configured in the console. If you hasn’t generated the key or the App public key hasn’t been configured in the console, then see the subsequent procedure Configure application public key.
- Recommended: Put the RSA key in /META-INF/config/rsa-mpc-pri-key-{env}.der where {env} indicates the workspace, such as dev, sit, prod, and so on.

You can declare the API service through Spring or Spring Boot.

Declare through Spring

In the Spring configuration file of the corresponding bundle, declare the above service’s Spring Bean. Code sample:
```
<bean id="mockRpc" class="com.alipay.gateway.spi.mpc.test.MockRpcImpl"/>
```

In the Spring configuration file of the corresponding bundle, declare com.alipay.gateway.spi.mpc.MpcServiceStarter type Spring Bean.MpcServiceStarter registers all beans with @OperationType to the specified registration center through mpaaschannel protocol. Code sample:

 <bean id="mpcServiceStarter" class="com.alipay.gateway.spi.mpc.MpcServiceStarter">
     <property name="registryUrl" value="${registry_url}"/>
     <property name="appName" value="${app_name}"/>
     <property name="workspaceId" value="${workspace_id}"/>
     <property name="projectName" value="${project_name}"/>
     <property name="privateKeyPath" value="${privatekey_path}"/>
 </bean>

Declare through Spring Boot

Declare the above service’s Spring Bean through annotation. Code sample:
```
@Service
public class MockRpcImpl implements MockRpc{
}
```

Declare com.alipay.gateway.spi.mpc.MpcServiceStarter type Spring Bean through annotation.MpcServiceStarter registers all beans with @OperationType to the specified registration center through mpaaschannel protocol. Code sample:

 @Configuration
 public class MpaaschannelDemo {
     @Bean(name="mpcServiceStarter")
     public MpcServiceStarter mpcServiceStarter(){
         MpcServiceStarter mpcServiceStarter = new MpcServiceStarter();
         mpcServiceStarter.setWorkspaceId("${workspace_id}");
         mpcServiceStarter.setAppName("${app_name}");
         mpcServiceStarter.setRegistryUrl("${registry_url}");
         mpcServiceStarter.setProjectName("${project_name}");
         mpcServiceStarter.setPrivateKeyPath("${privatekey_path}");
         return mpcServiceStarter;
     }
 }

Configure MPC log

For better troubleshooting, you can configure the logs related to MPC on demand. For example, to configure log4j:

<!-- [MPC Logger] tenant link, record information of settings and establishing link -->
<appender name="MPC-TENANT-LINK-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="file" value="${log_root}/mpaaschannel/tenant-link.log"/>
    <param name="append" value="true"/>
    <param name="encoding" value="${file.encoding}"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
    </layout>
</appender>

<!-- [MPC Logger] Record the relevant data of a stream (including a pair of tenant stream <-> component stream) -->
<appender name="MPC-STREAM-DATA-APPENDER" class="org.apache.log4j.DailyRollingFileAppender">
    <param name="file" value="${log_root}/mpaaschannel/stream-data.log"/>
    <param name="append" value="true"/>
    <param name="encoding" value="${file.encoding}"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d [%X{remoteAddr}][%X{uniqueId}] %-5p %c{2} - %m%n"/>
    </layout>
</appender>

<!-- [MPC Logger] tenant log -->
<logger name="TENANT-LINK-DIGEST" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPC-TENANT-LINK-APPENDER" />
    <appender-ref ref="ERROR-APPENDER" />
</logger>

<!-- [MPC Logger] component log -->
<logger name="STREAM-DATA-DIGEST" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPC-STREAM-DATA-APPENDER" />
    <appender-ref ref="ERROR-APPENDER" />
</logger>

Configure application public key

Go to the configuration page of Interface keys.
1. Log in to the console, select Products and Services > mPaaS to go to mPaaS console.
2. Choose the correct workspace, click the name of the application to access API service.
3. On the left navigation bar, select Manage Codes > Interface Keys to go to the configuration page.

Click Configure on the top right corner, enter the public key content (make sure that the space or empty line at the bottom is removed), and then submit.

Note: The RSA key must be 2048 bit, with Base64 encoded.

Follow these steps to generate RSA key:

Install openssl tool.

Execute the following command to generate private key file private_key_base64.der and public key file public_key_base64.der.

 * ### 1. Generate a 2048-bit RSA private key
 * $ openssl genrsa -out private_key.pem 2048
 *
 * ### 2. Convert private Key to PKCS#8 format (so Java can read it)
 * $ openssl pkcs8 -topk8 -inform PEM -outform DER -in private_key.pem -out private_key.der -nocrypt
 *
 * ### 3. Output public key portion in DER format (so Java can read it)
 * $ openssl rsa -in private_key.pem -pubout -outform DER -out public_key.der
 *
 * ### 4. change to base64:
 * ## Generated private key, configured in backend application
 * $ openssl base64 -in private_key.der -out private_key_base64.der
 * ## Generated public key
 * $ openssl base64 -in public_key.der -out public_key_base64.der
 *
 * ### remember to clear the whitespace chars and line breaks before submit!!!

Register API group

On the left navigation bar, click Manage Backend Services > Mobile Gateway to go to mobile gateway configuration page.
Click API group tab to open API group list, then click Create API group.
In the pop-up dialog box, enter or select the corresponding information.
- Type: Select MPC.
- API group: Required, it is the name of the business system which provides services.
- Project name: Required, it defaults to the Project Name of the current workspace.
- Timeout period: Optional, it is the timeout period (in ms) for sending requests to the business system. It defaults to 3,000 ms.
Click OK to submit.
For more configuration of API group, see Configure MPC group.

Register API service

Click Manage API tab to open API list, then click Create API.
In the pop-up dialog box, select MPC as API type, select API group, and check the required services from the obtained operationType list, then click OK.

Configure API service

Click the Configure in the operation column of API list to go to API configuration page.
In API configuration page, click Edit on the corresponding area to edit, and then click Save.
Notes:
- To fast go through, you can turn off the Verify signature in Advanced settings. See Instructions on backend signature verification for more information.
- For the detailed API configuration, See Configure API.
Check the switch on the top right corner to make sure that API service is On. (Only the API services turned On can be called.)

Test API service

See Test API for more information.

Generate client SDK

See Generate codes for more information.

Result

After completing the steps above, API service can be called by client. For more detailed information of client development, see Client development guide: