API Connector

Overview

Persistent Mobile Foundation applications can invoke microservice or enterprise backend service using PMF adapters. Writing the adapter needs an understanding of the PMF adapter framework. As an alternative, PMF facilitates secure calls to microservice or enterprise backend service without involving adapters through PMF API connector. The API connector, like an adapter, ensures secure invocations based on PMF’s OAuth 2.0 mechanism. With API Connector, PMF administrator can configure and deploy microservice or enterprise backend service details in PMF. The deployed configuration is used by PMF runtime to securely invoke microservice or backend service requests from a mobile app.

Benefits

Using PMF API connector has the following benefits.

Loosely coupled backend to integrate with microservices.
Detailed app and API analytics.
Clean integration with Backend for Frontend (BFF) patterns for cross-channel architectures (web, mobile, or others) with a single microservice layer.
Better performance tuning across channels and backends.
Less dependent on PMF adapter technology skill.
Out-of-the-box app management.
Light-weight runtime.
Reliable and scalable runtime with no user code.

Using API Connector

To use the API Connector, you need to follow the following two steps.

Define and deploy microservice or backend service configuration to PMF server.
Modify the client app to invoke the microservice or backend service methods through the deployed configuration.

Flow

As shown in the diagram, the first step is to configure and deploy the microservice or enterprise backend service details in the PMF server using the administration management API. The PMF runtime securely invokes client requests to appropriate microservice or enterprise backend by using the deployed configuration.

The OAuth based PMF security mechanism ensures that the call is made by a legitimate application client. The PMF client SDK and PMF authorization server, under the hood, validates the request that is made by the application. The enterprise backend service is invoked against satisfactory security validations.

API connector flow

Define and Deploy microservices or enterprise backends configuration

PMF administration management API can be used to configure and deploy the microservice or enterprise backend details that the client app needs to connect to.

PMF administration management API is available as a part of PMF server installation.

The management API used for this purpose is,

http://<host>:<port>/mfpadmin/management-apis/2.0/runtimes/mfp/backend-services-config

The following methods are available for the configuration API to manage the backend service details from PMF.

Use POST to deploy backend service configurations.
Use GET to retrieve deployed backend service configurations.
Use DELETE to delete the previously deployed configurations.

The POST API takes the service configuration details in a JSON format. Following is the configuration JSON syntax.

{
"backendServices" : [
    {
        "service": "resorts",
        "baseUrl":"http://mybluemix.net/resorts",
        "auth" : {
            "type" : "basic",
            "credential" : {
                "username" : "user",
                "password" : "pass"
            }
        },
        "ConnectionProperties" : {
            "maxConnetions" : "50",
            "connectionTimeoutInMilliseconds" : "20000",
            "socketTimeoutInMilliseconds" : "20000"
        }
    }
]
}

The keys that are used in the JSON is explained in the following lines.

service – Logical service name to identify the microservice or backend enterprise service. This should be a unique name for the particular service in the list of services that are configured in your PMF server by using this management API.
baseurl – Base URL of microservice or enterprise backend service. This is the complete URL of the microservice that exposes the methods that can be called by the client app. The method name could be provided by the client application.
auth – Authentication details to be used to access the enterprise backend service.
- type – PMF supports following three types,
  - ‘basic’ – Basic authentication along with ‘credentials’ section to configure the username and password. For example,
```
 "credential" : {
     "username" : "hello",
     "password" : "hello"
 }
```
  - apikey – For API key based authentication, a variety of different schemes are supported based on the policy type. Following is the syntax for apikey.
```
 "type" : "apikey",
 "credential" : {
     "apikey" : "abcdefg",
     "policy" : "basic",
     "name" : "apikey"
 }
```
    The policy can be header, query, or basic based on how the backend service expects the API key (apikey) to be presented to it. The policy value header shall forward apikey in request header with header name that is indicated by name. Policy query sends apikey as query param and policy basic sends apikey as basic auth.
  - mfpauth – In this type, the microservice can leverage the PMF OAuth based security mechanism. The credentials section is not required for the mfpauth type and need not to be part of configuration JSON.
  The backend service can be protected by security scope, authorization server, and PMF auth server. Before providing access to backend service, PMF auth mechanism ensures that the request carries valid access token with the necessary scope. When PMF auth server confirms the validity of the access token that is presented during introspection, access to backend service is granted. For details about how to configure backend service to use PMF auth server, see here.
  - extauth – This type can be used to support backend microservices using external or third party auth server. The application client should pass the access token expected by the backend service as a special header named ext-token. The API connector shall forward the access token received as part of ext-token header from app client as Authorization header to backend microservice. The credential section is not required in case of extauth type and need not be part of configuration JSON. The external token introspection and renewal after token expiry will have to be handled by the app client and backend microservice. The PMF security mechanism to validate the app client remains the same.
The ConnectionProperties can be used to configure connection parameters between the PMF server and backend microservices. These parameters are optional and if not provided shall use default values. Following is the syntax for ConnectionProperties.
```
 "ConnectionProperties" : {
     "maxConnetions" : "50",
     "connectionTimeoutInMilliseconds" : "20000",
     "socketTimeoutInMilliseconds" : "20000"
 }
```
Following are the default values for individual connection parameters.
- maxConnetions => 20
- connectionTimeoutInMilliseconds => 30000 (that is, 30 seconds)
- socketTimeoutInMilliseconds => 30000 (that is, 30 seconds)

Following is the syntax for the admin API curl commands.

POST to deploy the configurations.

 curl -X POST -u admin:admin 'http://<host>:<port>/mfpadmin/management-apis/2.0/runtimes/mfp/backend-services-config' --header 'Content-Type: application/json' --data-binary  @config.json

Where config.json is the JSON file with configurations similar to the above JSON syntax.

GET to fetch the existing configurations.

 curl -X GET -u admin:admin 'http:// <host>:<port>/mfpadmin/management-apis/2.0/runtimes/mfp/backend-services-config'

DELETE to remove the existing deployed configurations.

 curl -X DELETE -u admin:admin 'http:// <host>:<port>/mfpadmin/management-apis/2.0/runtimes/mfp/backend-services-config'

After the microservice or backend service configuration is deployed to PMF, you can use the PMF Client SDK to invoke the enterprise backend service. For more information on client SDK API, see here.

Using WLResourceRequest to access external microservices

The WLResourceRequest API can be used to allow mobile apps access to microservices hosted outside of PMF. PMF facilitates secure calls to microservice or enterprise backend service without involving adapters through PMF API Connector. The API Connector, like an adapter, ensures secure invocations based on PMF’s OAuth 2.0 mechanism. With API Connector, PMF administrator can configure and deploy microservice or enterprise backend service details in PMF. The deployed configuration is used by PMF runtime to securely call microservice or backend service requests from the mobile app.

Note: For more information on resource request APIs, see here.

To access a microservice URL such as http://mybluemix.net/resorts/cities and the PMF runtime backend service is configured as follows.

{
  "service": "resorts",
  "baseUrl":"http://mybluemix.net/resorts"
}

WLResourceRequest can be defined as

var options = { timeout, backendServiceName}
WLResourceRequest request = new WLResourceRequest(url,WLResourceRequest.GET, options);

url : Relative URL of the microservice endpoint. For example : cities
method : HTTP method to use. For example : WLResourceRequest.GET
backendServiceName : Name of the backend service configured on server to fetch data from. For example, resorts.
timeout : The timeout in milliseconds for this request.

▲

Last modified on