API Connector

improve this page | report issue

Overview

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

Note: Mobile Foundation introduced API connector in iFix 8.0.0.0-MFPF-IF202006021507.

Benefits

Using Mobile Foundation 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 Mobile Foundation 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 Mobile Foundation 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 Mobile Foundation server using the administration management API. The Mobile Foundation runtime securely invokes client requests to appropriate microservice or enterprise backend by using the deployed configuration.

The OAuth based Mobile Foundation security mechanism ensures that the call is made by a legitimate application client. The Mobile Foundation client SDK and Mobile Foundation 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

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

Mobile Foundation administration management API is available as a part of Mobile Foundation 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 Mobile Foundation.

  1. Use POST to deploy backend service configurations.
  2. Use GET to retrieve deployed backend service configurations.
  3. 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.

  1. 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 Mobile Foundation server by using this management API.
  2. 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.
  3. auth – Authentication details to be used to access the enterprise backend service.
    • type – Mobile Foundation 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 Mobile Foundation 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 Mobile Foundation auth server. Before providing access to backend service, Mobile Foundation auth mechanism ensures that the request carries valid access token with the necessary scope. When Mobile Foundation 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 Mobile Foundation 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 Mobile Foundation security mechanism to validate the app client remains the same.
  4. The ConnectionProperties can be used to configure connection parameters between the Mobile Foundation 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.

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

  2. 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'
    
  3. 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 Mobile Foundation, you can use the Mobile Foundation 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 Mobile Foundation. Mobile Foundation facilitates secure calls to microservice or enterprise backend service without involving adapters through Mobile Foundation API Connector. The API Connector, like an adapter, ensures secure invocations based on Mobile Foundation’s OAuth 2.0 mechanism. With API Connector, Mobile Foundation administrator can configure and deploy microservice or enterprise backend service details in Mobile Foundation. The deployed configuration is used by Mobile Foundation 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 Mobile Foundation 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.
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on July 15, 2020