developer portal

Documentation

edgeSDK for microservice devs

Prerequisites

  1. Download and install the latest version of edgeSDK on your computer.

Important: Please follow the installation guide after download.

  1. Download and install the latest edgeSDK OAuth Tool on your computer.
  2. Download and install the latest version of node.js on your computer.
  3. Download and install the latest version of Git on your computer.
  4. Create your mimik developer account here.

Step 1. Create an edgeSDK project

  1. Sign in to mimik developer console.
  2. In the mimik developer console, click Create Project.
  3. Enter a Project Name.
  4. Upload a logo image if you want to use your own Project Logo.
  5. Submit the form with the auto-generated Redirect URI or enter your own.

Important: edgeSDK uses OAuth 2.0 for authentication and a redirect URI is necessary for the process. The standard format of redirect URI is com.<string>://<string>. You can learn more about it here.

Step 2. Authenticate and authorize edgeSDK on your machine

  1. Login from the developer console and click on Open OAuth Tool under Projects.

Important: This will launch the installed OAuth Tool on your computer.

  1. Select your intended edgeSDK project for developing your current microservice.
  2. Click Get edge Access Token and login again in the prompted session.
  3. After successfully logging in, the Associate Device button should now be active.
  4. Click Associate Device; edgeSDK should now be authenticated and authorized on your machine.

Important: The OAuth Tool can provide edge access token, which allows you to deploy and run your edge microservice.

Step 3. Set up your development environment

For new developers, we provide a simple 'hello world' template for you to get started with edge microservice development, using express.js like API interface.

git clone https://github.com/mimikgit/starter-microservice.git <folder name>

Continue this guide after you have cloned the above GitHub repository.

Step 4. Building your starter microservice

  1. In the directory of the starter microservice, install microservice dependencies, you can simply use this command:
npm i
  1. Now, simply run the following command to minimize the build:
npm run build
  1. Next, simply run the following command and your image file will be packed under the folder that you specify under config/default.yml
npm run package

Step 5. Deploying your starter microservice

  1. Run the following command under the build directory to deploy the image to edgeSDK container runtime:

Note: For Windows users, please change the single quote to double quote and vice versa for following CURL commands.

Note: Replace the <edge Access Token> with the edge Access token you obtain from Step 2 above.

curl -i -H 'Authorization: Bearer <edge Access Token>' -F 'image=@microservice-v1.tar' http://localhost:8083/mcm/v1/images
  1. Run the following command to start the container image with your environment variables:

Note: For Windows users, please change the single quote to double quote and vice versa for following CURL commands.

curl -i -H 'Authorization: Bearer <edge Access Token>' -d '{"name": "microservice-v1", "image": "microservice-v1", "env": {"MCM.BASE_API_PATH": "/sample/v1"} }' http://localhost:8083/mcm/v1/containers

Example Response:

{
  "created": 1579560851322,
  "env": {
    "MCM.BASE_API_PATH": "/xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/sample/v1",
    "MCM.WEBSOCKET_SUPPORT": "false"
  },
  "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-microservice-v1",
  "image": "microservice-v1",
  "imageId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-microservice-v1",
  "name": "microservice-v1",
  "state": "started" // This response indicated the edge microservice is currently running!!!!
}

Important: The API endpoints of your starter microservice is followed by the MCM.BASE_API_PATH from your CURL response. Let's copy it and use it for the next step.

Step 6. Making API request to starter microservice

You can get a response from your starter microservice simply by calling the HTTP API:

curl http://localhost:8083/<MCM.BASE_API_PATH>/

Expected response:

Hello World!

Hint: You can also make API request to your starter microservice from browser on your device or API client such as Postman.

Step 7. Modify your starter microservice

Now, let's modify the starter microservice to get a list of our edgeSDK powered devices in our local network.

  1. Go to the directory of starter microservice and navigate to src directory.
  2. Under the index.js file, add the following piece of code to get the edgeSDK linkLocal clustering information:
app.get('/localDevices', (request, response) => {
      context.http.request(({
        url: 'http://localhost:8083/mds/v1/nodes?clusters=linkLocal',
        success: function(r) {
          if (!request.authorization) {
            response.status = 403;
            response.end(JSON.stringify({ 'msg': 'missing bearer token' }, 2, null));
            return;
          }
          const authorization = request.authorization.split(' ');
          if (authorization.length < 2) {
            response.status = 403;
            response.end(JSON.stringify({ 'msg': 'missing bearer token' }, 2, null));
            return;
          }
          const token = authorization[1];
          const nodes = JSON.parse(r.data);
          const data = JSON.stringify(nodes.data);

          context.edge.decryptEncryptedNodesJson({
            type: 'local',
            data,
            token,
            success: function(result) {
              response.end(JSON.stringify(JSON.parse(result.data), null, 2));
            },
            error: function(err) {
              response.end(err.message);
            }
          });
        },
        error: function(err) {
          response.end(err.message);
        }
      }));
    });
  1. After the modification, remember to save the file and repeat Step. 4 and 5 to build and deploy the updated starter microservice again.

Hint: Now, you will probably notice that MCM.BASE_API_PATH does not change from your new deployment since it is associated to your project on mimik developer console.

Step 8. Get devices in your local edgeSDK cluster

Our newly added endpoint is protected by edge Access Token, so we can only make the HTTP call programmatically from application, curl or API client. In this example, we will be using CURL:

curl -i -H 'Authorization: Bearer <edge Access Token>' http://localhost:8083/<MCM.BASE_API_PATH>/localDevices

Example response:

{
  "localLinkNetwork": {
    "localLinkNetworkId": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "nodes": [ // array contains all the edge nodes within your local network.
      {
        "APIVersion": "v1",
        "account": {
          "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // account ID of the edge node
          "self": ""
        },
        "addresses": [
          {
            "type": "local",
            "url": {
              "href": "http://x.x.x.x:8083" // url of the edge node
            }
          }
        ],
        "characteristics": [
          {
            "name": "cpu",
            "value": "Intel(R) Core(TM) i7-8500U" // cpu of the edge node
          },
          {
            "name": "edgeVersion",
            "value": "v2.2.0" // edgeSDK version on the edge node
          },
          {
            "name": "os",
            "value": "linux" //operating system of the edge node
          },
          {
            "name": "totalPhysicalMemory",
            "value": "2061750272" //total RAM in bits of the edge node
          },
          {
            "name": "totalStorage",
            "value": "15784157184" //total Disk space in bits of the edge node
          }
        ],
        "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // node ID of the edge node
        "networkAddress": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "rolesInCluster": [
          "superNodeLocalLinkNetwork" // the role of the edge node
        ],
        "services": [ // the edge microservices deployed on the edge node
          {
            "id": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-microservice-v1",
            "serviceType": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-microservice-v1",
            "tenant": {
              "id": "",
              "self": ""
            }
          }
        ],
        "tenant": {
          "id": "mimik|001",
          "self": ""
        }
      }
    ]
  }
}

Final Step. Develop your own solution

Now, you can start your journey to develop your own edge microservice by following our edgeSDK Serverless APIs.

Need more help?

Feel free to contact us on stack overflow or send us a question via our support page if you have any questions.

Was this page helpful?