Objective

The objective of this article is to demonstrate how to use the mimik Client Library interfaces when working with edge microservices in an iOS project.

Intended Readers

The intended readers of this document are iOS software developers, who want to familiarize themselves with the basics of mimik Client Library interfaces, specifically methods for interfacing with edge microservices.

What You'll Be Doing

In this tutorial, you will learn about key topics related to working with the mimik Client Library edge microservice interfaces. These topics include:

• Deploying
• Referencing
• Calling
• Updating
• Undeploying

Prerequisites

• Understanding the mimik Client Library components integration and initialization process as layed out in this article.

• Understanding how to work with the mim OE Runtime in an iOS application.

• Attaching a real iOS device to the development Mac and selecting it as the build target. This won't work with the iOS simulator.

Deploying an edge Microservice

Once the mimik Client Library has been integrated and initialized in your project, mim OE Runtime started and Access Token generated, we can get into the specifics of working with edge microservices.

You can think of deploying (installing) edge microservices as spinning up individual micro servers within your application. The code example below in Listing 1 shows you how to do this. A detailed explanation follows.

1: // We pass the Access Token required to deploy the edge microservice as a parameter. See "Creating an Access Token" in the previous tutorial
2: func deployMicroservice(accessToken: String) async -> Result<EdgeClient.Microservice, NSError> {
3: 
4:     // Application's bundle reference to the edge microservice tar file
5:     guard let imageTarPath = Bundle.main.path(forResource: "randomnumber_v1", ofType: "tar") else {
6:         // Tar file not found, returning failing
7:         return .failure(NSError.init(domain: "Error", code: 404))
8:     }
9: 
10:     // edge microservice deployment configuration object with example values
11:     let config = EdgeClient.Microservice.Config(imageName: "randomnumber-v1", containerName: "randomnumber-v1", basePath: "/randomnumber/v1", envVariables: ["some-key": "some-value"])
12: 
13:     // Calling mimik Client Library method to deploy the edge microservice
14:     switch await self.edgeClient.deployMicroservice(edgeEngineAccessToken: accessToken, config: config, imageTarPath: imageTarPath) {
15:     case .success(let microservice):
16:         print("Success", microservice)
17:         // Call successful, returning success with the deployed edge microservice object reference
18:         return .success(microservice)
19:     case .failure(let error):
20:         print("Error", error.localizedDescription)
21:         // Call unsuccessful, returning failure
22:         return .failure(error)
23:     }
24: }

Listing 1: Deploying an edge microservice

First, we establish a file path to where the edge microservice is stored within the application's bundle. In this example, the edge microservice is represented by a randomnumber_v1.tar file according to the Bundle.main.path(forResource: "randomnumber_v1", ofType: "tar") statement.

Next, we create a configuration object using the function EdgeClient.Microservice.Config(). This configuration object describes the edge microservice deployment parameters. The example code in Listing 1 is configured with some hard-coded values. In a production setting, you'd want to put these values somewhere in a loadable configuration file.

Then, we call the deployMicroservice() method of the mimik Client Library which requires the following parameters:

edgeEngineAccessToken is the Access Token we generated in the "Creating an Access Token" section of the previous tutorial.

config is a configuration object describing the edge microservice deployment parameters.

imageTarPath is a file path to where the edge microservice is stored within the application's bundle.

After the call, we validate the result.

If successful, we get a reference object to the deployed edge microservice and return it. Developer can either keep a reference to this object or get it again as needed later, as described in the next section below.

If unsuccessful, we return a failure.

At this point we are done, the edge microservice has been successfully deployed and is now ready to start responding to calls.

Take a moment to review the statements in the code above using these comments as your guide.

Referencing edge microservice

After deploying an edge microservice, you may want to start calling its endpoints to perform tasks. Since the endpoints use the http communication protocol, you'll need to establish a URL to access them. There are several ways to accomplish this, but for the purposes of this tutorial, we will establish the URL using an edge microservice object reference.

The code example in Listing 2 below demonstrates how to do this. A detailed explanation follows the listing.

1: // We pass the Access Token required to find the deployed edge microservice as a parameter. See "Creating an Access Token" in the previous tutorial
2: func deployedMicroservice(accessToken: String) async -> Result<EdgeClient.Microservice, NSError> {
3:     
4:     // Getting a reference to the deployed edge microservice named "randomnumber-v1"
5:     guard case let .success(microservice) = await
6:             self.edgeClient.microservice(containerName: "randomnumber-v1", edgeEngineAccessToken: accessToken) else {
7:         print(#function, #line, "Error")
8:         // We don't have the reference, returning a failure.
9:         return .failure(NSError(domain: "Deployment Error", code: 500))
10:     }
11:     
12:     // Establishing the full path url to edge microservice's /randomNumber endpoint
13:     guard let endpointUrlComponents = microservice.fullPathUrl(withEndpoint: "/randomNumber"), let endpointUrl = endpointUrlComponents.url else {
14:         print(#function, #line, "Error")
15:         // We don't have the url, returning a failure.
16:         return .failure(NSError(domain: "Microservice Error", code: 500))
17:     }
18:             
19:     print(#function, #line, "Success", microservice, endpointUrl)
20:     // We have the random number from the edge microservice, returning a success with the value
21:     return .success(microservice)
22: }

Listing 2: Referencing an edge microservice

First, we call the microservice method of the mimik Client Library, which requires the parameters:

containerName is the name of the edge microservice container we want to reference. In our example we call it randomnumber-v1.

edgeEngineAccessToken is the Access Token we generated in the "Creating an Access Token" section of the previous tutorial.

After making the call, we perform result-validation checks.

If the call is successful, we obtain a reference to the deployed edge microservice and return it as a success.

If there is an issue, we return a failure.

For the purposes of this tutorial, we will attempt to construct a full path URL to the deployed edge microservice endpoint, specifically /randomNumber. For now, we will simply print the value to the console log. In the next section, we will actively capture and use this value.

Take a moment to review the code above, using these comments as your guide.

Calling edge microservice

Once the URL to the deployed edge microservice endpoint has been established, we can begin making http calls to it. The code example in Listing 3 below demonstrates how to do this. A detailed explanation follows the listing.

1: import Alamofire
2: 
3: // We pass the Access Token required to list the deployed edge microservices as a parameter. See "Creating an Access Token" in the previous tutorial
4: func callMicroservice(accessToken: String) async -> Result<Any, NSError> {
5:     
6:     // Getting a reference to the deployed edge microservice named "randomnumber-v1"
7:     guard case let .success(microservice) = await
8:             self.edgeClient.microservice(containerName: "randomnumber-v1", edgeEngineAccessToken: accessToken) else {
9:         print(#function, #line, "Error")
10:         // We don't have the reference, returning a failure.
11:         return .failure(NSError(domain: "Deployment Error", code: 500))
12:     }
13:     
14:     // Establishing the full path url to edge microservice's /randomNumber endpoint
15:     guard let endpointUrlComponents = microservice.fullPathUrl(withEndpoint: "/randomNumber"), let endpointUrl = endpointUrlComponents.url else {
16:         print(#function, #line, "Error")
17:         // We don't have the url, returning a failure.
18:         return .failure(NSError(domain: "Microservice Error", code: 500))
19:     }
20:     
21:     // Alamofire library request call to the endpoint's full path url, with serialization of a Decodable Int value
22:     let dataTask = AF.request(endpointUrl).serializingDecodable(Int.self)
23:     guard let value = try? await dataTask.value else {
24:         print(#function, #line, "Error")
25:         // Response value serialization unsuccessful, returning a failure
26:         return .failure(NSError(domain: "Decoding Error", code: 500))
27:     }
28:     
29:     print(#function, #line, "Success", value)
30:     // Response value serialization successful, returning success with the serialized value
31:     return .success(value)
32: }

Listing 3: Calling edge microservice

To simplify the code, we will use an established Swift networking library called Alamofire. Since the Alamofire library is already a dependency of the mimik Client Library, it is made available to our iOS project as part of the CocoaPods dependency manager automatically.

First, we make the Alamofire library available to our class, by importing it.

Next, we get a reference to deployed randomnumber-v1 edge microservice and the full path URL to its /randomNumber endpoint.

At this point, we are ready to use the request() method of the Alamofire Library to make the http call to the edge microservice endpoint.

We set only one parameter in the request() method:

convertible is the full path url to the endpoint of the deployed edge microservice we established a step earlier.

Once the http call is made, we perform a validation check to ensure that the response matches our expectations. In this example, we are expecting an Int value in the response.

If there is an issue, we return a failure.

If the response is valid and an integer value is received, we return a success along with the received value.

Take a moment to review the code above, using these comments as your guide.

Updating an edge microservice

As an iOS developer, you might be asked to update an already deployed edge microservice. For example, when the edge microservice developer releases a new version that might include bug fixes or new features.

There are two ways to update an already deployed edge microservice.

You could re-deploy the same edge microservice from a new, changed .tar file. You have to be careful, though, to use exactly the same configuration that was used during the initial deployment. This is so that you don't end up with two instances of the same edge microservice, running with different configurations.

Instead, you should safely call the update method on the mimik Client Library. Using this method guarantees that only the specific, referenced edge microservice gets updated.

The code example below in Listing 4 shows you the recommended, safer way of updating an already deployed edge microservice. A detailed explanation follows the code example.

1: // We pass the Access Token required to update the deployed edge microservices as a parameter. See "Creating an Access Token" in the previous tutorial
2: func updateMicroservice(accessToken: String) async -> Result<EdgeClient.Microservice, NSError> {
3:     
4:     // Getting a reference to the deployed edge microservice named "randomnumber-v1"
5:     guard case let .success(microservice) = await
6:             self.edgeClient.microservice(containerName: "randomnumber-v1", edgeEngineAccessToken: accessToken) else {
7:         print(#function, #line, "Error")
8:         // We don't have the reference, returning a failure.
9:         return .failure(NSError(domain: "Deployment Error", code: 500))
10:     }
11:     
12:     // Calling mimik Client Library method to update the edge microservice environment variables
13:     switch await self.edgeClient.updateMicroserviceEnv(edgeEngineAccessToken: accessToken, microservice: microservice, envVariables: ["some-new-key": "some-new-value"]) {
14:     case .success(let microservice):
15:         print("Success", microservice)
16:         // Call successful, returning success with the updated edge microservice reference
17:         return .success(microservice)
18:     case .failure(let error):
19:         print("Error updating microservice", error.localizedDescription)
20:         // Call unsuccessful, returning failure
21:         return .failure(NSError.init(domain: "Error", code: 500))
22:     }
23: }

Listing 4: Updating an edge microservice

First, we get an object reference to the already deployed edge microservice.

Then, we call the update method on the mimik Client Library, which requires the following parameters:

edgeEngineAccessToken is the Access Token we generated in the "Creating an Access Token" section of the previous tutorial.

microservice is the object reference to the deployed edge microservice that we established in the previous step.

envVariables are any environment configuration values for the edge microservice. All need to be explicitly set, every time.

After the call, we validate the result.

If the edge microservice update was successful, we obtain a reference to the updated edge microservice and return it as a success.

If there was an issue, we return a failure.

At this point, the edge microservice has been successfully updated, and the process is complete.

Take a moment to review the code above, using these comments as your guide.

Undeploying an edge microservice

Sometimes there is a need to undeploy (uninstall) an edge microservice from the mim OE Runtime. The code example below in Listing 5 shows how to accomplish this. A detailed discussion follows the code example.

1: // We pass the Access Token required to update the deployed edge microservices as a parameter. See "Creating an Access Token" in the previous tutorial
2: func undeployMicroservice(accessToken: String) async -> Result<Void, NSError> {
3:     
4:     // Getting a reference to the deployed edge microservice named "randomnumber-v1"
5:     guard case let .success(microservice) = await
6:             self.edgeClient.microservice(containerName: "randomnumber-v1", edgeEngineAccessToken: accessToken) else {
7:         print(#function, #line, "Error")
8:         // We don't have the reference, returning a failure.
9:         return .failure(NSError(domain: "Deployment Error", code: 500))
10:     }
11:     
12:     // Calling mimik Client Library method to undeploy the referenced edge microservice
13:     switch await self.edgeClient.undeployMicroservice(edgeEngineAccessToken: accessToken, microservice: microservice) {
14:     case .success:
15:         print("Success")
16:         // Call successful, returning a success
17:         return .success(())
18:     case .failure(let error):
19:         print("Error", error.localizedDescription)
20:         // Call unsuccessful, returning a failure
21:         return .failure(NSError.init(domain: "Error", code: 500))
22:     }
23: }

Listing 5: Undeploying an edge microservice

First, we get an object reference to the deployed edge microservice.

Then, we call the undeploy method on the mimik Client Library, which requires the following parameters:

edgeEngineAccessToken is the Access Token we generated in the "Creating an Access Token" section of the previous tutorial.

microservice is the object reference to the deployed edge microservice that we established in the previous step.

After the call, we validate the result.

If the edge microservice undeployment was successful, we return a success.

If there was an issue, we return a failure.

At this point, the edge microservice has been successfully undeployed and is no longer functional.

Take a moment to review the code above, using these comments as your guide.

Example Xcode project

You can download a fully functional example of an iOS application, showing all the functions discussed in the three iOS tutorials here. Download the project, run it on your iOS device and see all functions in action right away!

Additional reading

In order to get more out of this article, the reader could further familiarize themselves with the following concepts and techniques:

• Understanding the mimik Client Library for iOS.
• Creating a Simple iOS Application that Uses an edge microservice.
• Integrating the mimik Client Library into an iOS project.
• Working with mim OE in an iOS project.
• Working with AI language models in an iOS project.