Objective

The objective of this document is to describe the key concepts that developers need to understand to integrate the mimik Client Library with an iOS application and then use the library in their programming activities

Intended Readers

The intended readers of this document are iOS software developers and system integrators using the mimik Client Library when programming an iOS application

What You Need to Know Before You Start

In order to get the full benefit of this document, the intended readers should be familiar with the following:

• The basics of the purpose and use of the mimik edgeEngine Runtime
• The basics of using an Access Token to access and work with the edgeEngine Runtime
• The basics of programming iOS applications using the CocoaPods dependency management system

What You Will Learn from This Document

After reading this document, you will understand:

• The reason for using the mimik Client Library in your iOS application
• How to include the mimik Client Library as a project dependency in an iOS application using the CocoaPods dependency management system
• How the mimik Client Library is initialized for use in your iOS application at runtime
• How to use the mimik Client Library in your code to start and stop the edgeEngine Runtime installed on an application's host device
• How to use the mimik Client Library in your code to get and save a mimik Access Token in your application at runtime
• The concepts behind using the mimik Client Library to run and access an edge Microservice from within an iOS application
• How use the mimik Client Library to get additional information about the edgeEngine Runtime

Understanding the Purpose of the mimik Client Library

The purpose of the mimik Client Library is to provide a programmatic way to work with the edgeEngine Runtime to access information about the mobile device on which the application is running as well as mobile devices running within a cluster of mobile devices that are hosting the edgeEngine Runtime. Also, the mimik Client Library allows developers to use edge microservices running within a particular cluster.

The edgeEngine Runtime has the ability to transform a mobile device into an edge computing device. Edge computing is a distributed computing framework that allows independent devices such as cell phones, mobile tablets, and other IoT devices to do computationally intensive work internally using their own computing resources. Then, when the computation is completed, the result is passed on to other devices or back to a central server. It's the difference between having a cell phone that has the capability to do facial recognition using its own computing power as opposed to having to send a photo back for facial recognition processing at a central location. The benefit is that more useful work can be done faster, more flexibly while incurring less burden on the network.

Using the mimik Client Library allows developers to create applications that work with the edgeEngine Runtime to take advantage of the power and flexibility inherent in the edge computing paradigm.

Integrating the mimik Client Library using CocoaPods

At a high level integrating the mimik Client Library for use in an iOS project is a multi-phase process. These phases are:

• Integrating the mimik Client Library using the CocoaPods dependency manager
• Initializing the mimik Client Library
• Starting up the edgeEngine Runtime using the mimik Client Library
• Using the mimik Client Library in your iOS application

The following sections will describe the various aspects of the phases described above that developers need to understand to work with the mimik Client Library for iOS.

Create the Podfile

The mimik Client Library of iOS is a dependency that gets installed in an iOS project using the CocoaPods dependency manager. The following listing shows an example of a CocoaPods's Podfile that developers will include in their iOS project. The Podfile defines the source code repositories' location containing the relevant dependencies, as shown at Lines 2 -3. It also declares the particular pod for the mimik Client Library at Line 7.

1: platform :ios, '13.6'
2: source 'https://github.com/CocoaPods/Specs.git'
3: source 'https://github.com/mimikgit/CocoaPod-edge-specs.git'
4: 
5: target 'example' do
6:   use_frameworks!
7:   pod 'MIMIKEdgeMobileClient'
8: end

Running pod install against the Podfile

Once the dependencies are defined in thePodfile they can be used in the iOS Project. The developer will execute the command ...

 pod install

...to install the MIMIKEdgeMobileClient as well as other CocoaPod dependencies into the given iOS program. Running pod install against the Podfile described above will display output similar to the following.

 Analyzing dependencies
 Downloading dependencies
 Installing MIMIKEdgeMobileClient
 Installing Alamofire
 Installing AppAuth
 Installing JWTDecode
 Installing KeychainSwift
 Installing SwiftyJSON

At this point, the mimik Client Library is installed in the iOS project's workspace, ready for use in code.

Initializing the mimik Client Library

In order to get the mimik Client Library up and running in an iOS project, a developer needs to initialize it. Initialization involves importing a reference to MIMIKEdgeMobileClient and then creating an instance variable using the method, MIMIKEdgeMobileClient.init(license: nil).

The code listed below shows an example of a developer's code to create an instance of the mimik Client Library. Notice the call to MIMIKEdgeMobileClient.init(license: nil) as Line 3. This is the code that created the instance variable libary for MIMIKEdgeMobileClient.

1: import MIMIKEdgeMobileClient
2: lazy var mimikClientLibrary: MIMIKEdgeMobileClient = {
3:         let library = MIMIKEdgeMobileClient.init(license: nil)        
4:         guard let checkedLibrary = library else {
5:             fatalError()
6:         } 
7:         return checkedLibrary
8:     }()

You now have an initialized mimik Client Library into your iOS application.

Starting the edgeEngine Runtime

In order to do work using the mimik Client Library APIs, the host device on which iOS application will be running needs to have the edgeEngine Runtime binary installed and in a running state. Typically the edgeEngine Runtime is installed previously on the device hosting the particular iOS application under development. However, starting up the edgeEngine Runtime is work that the mimik Client Library does.

To start up the edgeEngine Runtime using the mimik Client Library, add the following code to your iOS project.

1: // Use the MIMIKStartupParameters object to configure the edgeEngine Runtime startup behavior
2: let edgeEngineStartupParameters = MIMIKStartupParameters.init(logLevel: .err, nodeInfoLevel: .on, nodeName: nil, localDiscovery: .off)
3: 
4: self.mimikClientLibrary.startEdgeEngine(startupParameters: edgeEngineStartupParameters) { result in
5:     guard result == true else {
6:         return
7:     }
8:     print("edgeEngine started")
9: }
10: 

Notice in the code above, at Line 1, the static method, MIMIKStartupParameters.init(), is used to create the startup parameters. Also, notice at Line 3 those startup parameters, edgeEngineStartupParameters, are used when starting the edgeEngine Runtime.

Authorizing Access to the edgeEngine Runtime

Most of the mimik Client Library APIs require an Access Token in order to be operational. Developers use the mimik Client Library to create an Access Token. The Access Token is based on the developer ID Token they generated when creating their account in the mimik Developer Portal. The following describes the process of generating and saving an Access Token using the mimik Client Library.

Getting the developer ID Token from the mimik Developer Portal.

Generating the Access Token that's used to work with various API within the mimik Client Library requires that they develop have a developer ID Token on hand. Developers get a developer ID Token from the mimik Developer Portal as shown in the illustration below.

A developer ID Token is generated within the particular mimik project registered on the mimik Developer Portal.

Generating the Access Token

Once developers have a developer ID Token in hand, they'll use it in code with the instance of the mimik Client Library in order to generate an Access Token.

The listing below shows code that a developer uses in an iOS application to generate an Access Token.

1: let developerIdToken = <DEVELOPER_ID_TOKEN>
2: 
3: self.mimikClientLibrary.authorizeWithDeveloperIdToken(developerIdToken: developerIdToken, completion: { result in
4:     
5:     guard result.error == nil, let checkedAccessToken = result.tokens?.accessToken, let checkedAccessTokenExpirationDate = result.tokens?.accessTokenExpirationDate else {
6:         return
7:     }
8:     
9:     print(#function, "\naccess token: ", checkedAccessToken, "\nexpires on: ", checkedAccessTokenExpirationDate)
10: })

WHERE: <DEVELOPER_ID_TOKEN> is the developer ID Token the developer retrieved from the mimik Developer Portal

Notice that the Access Token is the value of checkedAccessToken as set at Line 5 in the code above.

Saving the Access Token

Once the developers generate the Access Token, they save it internally in the iOS application using the method saveLibraryEdgeAccessToken from the mimik Client Library API. When the Access Token is saved using the mimik Client Library API, it will automatically be available to all subsequent API calls.

To save the Access Token generated previously using the mimik Client Library, developers use the following code in their iOS project.

 self.mimikClientLibrary.saveLibraryEdgeAccessToken(token: checkedAccessToken)

Stopping down the edgeEngine Runtime using the mimik Client Library

To shut down the edgeEngine Runtime, developers add the following code to their iOS project:

1: self.mimikClientLibrary.stopEdgeEngineSynchronously()
2: print("edgeEngine stopped")

Please note that due to the nature of edgeEngine shutdown process design, this call is intentionally synchronous, main thread blocking API.

Getting additional Information from the edgeEngine Runtime

The mimik Client Library provides a number of API methods that return information about a host device's edgeEngine Runtime and the environment in which the particular iOS application is running.

1: // get a link to the URL for the edgeEngine Runtime
2: let edgeEngineServiceLink = self.mimikClientLibrary.edgeEngineServiceLink()
3: // get the location of working directory where the edgeEngine Runtime is installed
4: let edgeEngineWorkingDirectory = self.mimikClientLibrary.edgeEngineWorkingDirectory()

The commented code above shows examples of some of the information a developer can get using the mimik Client Library API.

Deploying a microservice at the edge

Developers can use the mimik Client Library to deploy a microservice at the edge that's encapsulated in a pre-existing .tar file.

Sometimes the edge Image .tar file will be stored in a source code repository for immediate download. Other times that .tar file will need to be built from scratch using the source code for the edge Image. It all depends on the build and deployment policies of the given organization.

To learn the details of building an edge microservice into a deployable edge Image .tar file read, Deploying the edgeEngine Image for the microservice here.

The listing below shows the code a developer can use to deploy a microservice that is encapsulated in the .tar file fictitiously named microservice.tar and located at, /bundle/microservice.tar.

1: let accessToken = <ACCESS_TOKEN>>
2: let microserviceName = <MICROSERVICE_NAME>
3: let config = MIMIKMicroserviceDeploymentConfig.init(imageName: microserviceName, containerName: microserviceName, baseApiPath: "/\(microserviceName)/v1", envVariables: ["key" : "value"])
4: let imageTarPath = "/bundle/microservice.tar" // path to the microservice.tar in the application bundle
5: 
6: self.mimikClientLibrary.deployMicroservice(edgeEngineAccessToken: accessToken, config: config, imageTarPath: imageTarPath) { microservice in
7:     guard let checkedMicroservice = microservice else {
8:         return
9:     }
10:     print("deployed microservice: ", checkedMicroservice.container?.description ?? "N/A", checkedMicroservice.image?.description ?? "N/A")
11: }

Notice the use of the mimik Client Library API method, mimikClientLibrary.deployMicroservice() at Line 6.

WHERE:

• <ACCESS_TOKEN>> is the Access Token the developer generated previously using the mimik Client Library
• <MICROSERVICE_NAME> is the name of the of microservice as defined by the creator of the microservice.

Uninstalling an edge microservice deployment

The listing below shows the code a developer can use to undeploy (uninstall) an edge microservice from the edgeEngine Runtime running on an iOS device.

1: let accessToken = <ACCESS_TOKEN>>
2: let microserviceName = <MICROSERVICE_IMAGE_NAME>
3: let config = MIMIKMicroserviceUndeploymentConfig.init(imageName: microserviceName, containerName: microserviceName)
4: self.mimikClientLibrary.undeployMicroservice(edgeEngineAccessToken: accessToken, config: config) { result in
5:     guard result == true else {
6:         fatalError()
7:     }
8:     print("microservice undeployed success")
9: }

Add the above code to your iOS project. Notice the user of the static method, MIMIKMicroserviceUndeploymentConfig.init() at Line 3.

WHERE:

• <ACCESS_TOKEN>> is the Access Token the developer generated previously using the mimik Client Library
• <MICROSERVICE_NAME> is the name of the of microservice as defined by the creator of the microservice.

NOTE: The edgeEngine Runtime needs to be up and running for these API calls to work.

Calling an edge microservice

Once an edge microservice is deployed with the iOS application, a developer can work with it using the mimik Client Library.

1: import Alamofire
2: let deployedMicroservice: MIMIKMicroservice?
3: 
4: guard let checkedBaseAPIPath = self.deployedMicroservice?.baseAPIPath() else {
5:     continue
6: }
7: 
8: // Get the URL to the web server running within the edgeEngine Runtime
9: let edgeEngineServiceLink = self.mimikClientLibrary.edgeEngineServiceLink()
10: // Set the owner defined access code needed to create a unique, secure relationship between the iOS Application and the edge microservice
11: let ownerCode = <OWNER_DEFINED_ACCESS CODE>
12: // Append the <OWNER_DEFINED_ACCESS CODE> as a query parameter
13: let query = "?ownerCode=<OWNER_DEFINED_ACCESS CODE>"
14: // Append the query to the microservice endpoint
15: let endpointWithQuery = "<MICROSERVICE_ENDPOINT>" + query
16: // Create the full URL to the microservice 
17: let microserviceEndpointPath = edgeEngineServiceLink + checkedBaseAPIPath + "/" + endpointWithQuery
18: 
19: guard let url = URL.init(string: microserviceEndpointPath) else {
20:     return
21: }
22: 
23: let headers = ["Authorization" : "Bearer \(accessToken)"]
24: let httpHeaders = HTTPHeaders.init(headers)
25: 
26: AF.request(url, method: .get, parameters: nil, encoding: URLEncoding.default, headers: httpHeaders).responseJSON { response in
27:     guard let checkedDataJson = MIMIKEdgeMobileClient.validateMicroserviceResponse(response: response, encapsulatedData: false).dataJSON else {
28:         return
29:     }
30:     print(checkedDataJson)
31: }

The code listing above shows an example of how to access and use an edge microservice programmatically using the mimik Client Library.

WHERE

• <OWNER_DEFINED_ACCESS CODE> is [TBP]
• <MICROSERVICE_ENDPOINT> is [TBP]

Review

In this document you learned the following:

• The purpose of the mimik Client Library
• The operational concept behind integrating the mimik Client Library with iOS application code using the CocoaPods dependency manager
• The concepts and code behind programmatically initializing the mimik Client Library
• The concepts and code behind starting and stopping a host device's instance of the edgeEngine Runtime using the mimik Client Library
• The concepts and code behind using an Access Token in code to work with the mimik Client Library
• The concepts and code needed to get additional runtime information using the mimik Client Library
• The concepts and code needed to deploy a microservice at the edge using the mimik Client Library
• The concepts and code needed to uninstall (undeploy) a microservice using the mimik Client Library
• The concepts and code needed to work with a deployed edge microservice using the mimik Client Library