developer portal

Documentation

edgeSDK for microservice devs

Prerequisites

  1. Download and install the latest version of edgeSDK.

Important: After downloading edgeSDK, follow this installation guide.

  1. Download and install the latest edgeSDK OAuth Tool.
  2. Download and install the latest version of Node.js.
  3. Download and install the latest version of Git.
  4. Create a mimik developer account here.

Step 1. Create an edgeSDK project

  1. Sign in to the 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 this process. The standard format of a 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 OAuth Tool you just installed.

  1. Select the edgeSDK project that you have created from previous step.
  2. Click Get edge Access Token and login again in the prompted session.
  3. Click Associate Device and edgeSDK should now be authenticated and authorized on your machine.

Important: The OAuth Tool provides you with edge access tokens, which allows you to deploy and run your edge microservices.

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 with express.js like API interfaces. To use it, clone the following GitHub repository.

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

Step 4. Building a microservice

  1. Navigate to the folder of starter microservice that you have cloned, run the following command to install microservice dependencies:
npm i
  1. Run the following command to build the image of the microservice::
npm run build
  1. Run the following command to pack your image file in the folder that you specify under config/default.yml
npm run package

Step 5. Deploying a microservice

  1. Navigate to the build folder that specified under config/default.yml and run the following command to deploy the image to edgeSDK container runtime:

Important: Replace the <edge Access Token> with the edge Access token you obtained in Step 2.

Important: 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>' -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:

Important: 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 requests to microservice

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

Note: Replace the <MCM.BASE_API_PATH> with MCM.BASE_API_PATH from the response you get when you started your microservice from previous step.

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

Expected response:

Hello World!

Hint: You can also make API request to your starter microservice from your web browser or an API client like Postman.

Step 7. Modifying microservice

You can program microservice to do all sorts of things, such as getting a list of edgeSDK-powered devices on your local network.

  1. Navigate to the directory of starter microservice and navigate to src directory.
  2. Open the index.js file, go to the end of the file and add the following code to allow your microservice to retrieve your network's 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. Save index.js, then repeat Step 4 to re-build and re-package your microservice, and Step 5 to deploy and start it.

Hint: MCM.BASE_API_PATH will not change from re-deployment since it is associated to your project on mimik developer console.

Step 8. Get the 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. Developing your own microservices

To begin developing your own edgeSDK microservices, have a look at our edgeSDK Serverless APIs.

For more information for building edge microservices please visits here.

For more information for deploying edge microservices please visits here.

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?