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 are going to learn about topics relevant to working with the mimik Client Library edge microservice interfaces. These topics are:

• Deploying an edge Microservice
• Referencing an edge Microservice
• Calling an edge Microservice
• Updating an edge Microservice
• Undeploying an edge Microservice

Technical Prerequisites

In order to get full benefit from this article, the reader should have a working knowledge of the following concepts and techniques:

• A device running the latest iOS version.
• A familiarity of working with mimik Client Library components as described in thisKey Concepts article.
• An understanding of the mimik Client Library components integration and initializiation process as layed out in this article.
• An understanding of how to start the mim OE Runtime in an iOS application.
• An understanding of how to generate an mim OE Access Token.

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 edgeEngine 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
• config
• imageTarPath

WHERE

edgeEngineAccessToken is the mim OE 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 the deployment was successful, we get a reference object to the deployed edge microservice. Developer can either keep a reference to this object or get it again as needed later, as described in the next section below. In the last of Listing 1, we return the reference to the edge microservice as an object.

If there was an issue, we return a failure.

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

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

Referencing edge microservice

After edge microservice deployment, we will want to start calling its endpoints to do the work. Since the endpoint uses http communication protocols, we will need to establish a URL to reach it. There are several ways to accomplish this, but for the learning purposes of this tutorial, we will establish this URL using an edge microservice object reference. The code example below in Listing 2 shows how to do this. A detailed explanation follows the code listing.

1: // We pass the edgeEngine 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 and edgeEngineAccessToken

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

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

After the call, we do result-validation checks.

If the call was successful, we get a reference to deployed edge microservice, and so we return it as a success.

If there was an issue, we return a failure.

For learning purposes of this article, we attempt to establish a full path URL to the deployed edge microservice endpoint called /randomNumber. For now, we just print the value to the console log. In the next section, we will be actively capturing and using this value.

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

Calling edge microservice

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

1: import Alamofire
2: 
3: // We pass the edgeEngine 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 the convertible parameter in the request() method:

WHERE

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 do a validation check to make sure that we get the expected response. In our example, we are expecting an Int value in the response.

If there was an issue, we return a failure.

When all was good, and an Integer value was received, we return a success with the received value.

Take a moment to review the statements in 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 edgeEngine 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
• microservice
• envVariables

WHERE

edgeEngineAccessToken is the mim OE 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 get a reference object to the updated edge microservice, and then return it as a success.

If there was an issue, we return a failure.

At this point we are done, the edge microservice has been successfully updated.

Take a moment to review the statements in 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 edgeEngine 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
• microservice

WHERE

edgeEngineAccessToken is the mim OE 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 we are done, the edge microservice has been successfully undeployed and is no longer functional.

Take a moment to review the statements in 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 mimOE in an iOS project.
• Working with AI language models in an iOS project.