External Flex Services

As well as running in the FlexService Runtime, FlexServices can be deployed on any PaaS, local server, or hosting provider.

This guide covers the creation of FlexServices as well as running FlexServices outside of Kinvey.

Prerequisites

  1. Git for working with Kinvey repositories
  2. NodeJS v6.x and NPM (node package manager). We recommend installing NodeJS and NPM using NVM.

Creating a Flex Service

Creating a Flex service includes several steps, from configuring Kinvey Console to setting up a Node.js project. After you complete all the steps, you will have a Flex service ready to be deployed.

Setting Up Kinvey Console

Before you can deploy your Node.js project, you need to provision a Flex service using the Kinvey Console. The Flex service makes the connection between your Node.js project and the Kinvey backend.

Take the following steps to provision a Flex service:

  1. Log in to Kinvey Console.
  2. Select the Service Catalog tab and click Add a service.
  3. Select Flex and then External.
  4. Complete the form and finally click Save.
    • Name—Arbitrary name for the service.
    • Description—Optional details about the service.
    • Scope/App—App or organization that will use the service.
    • Secret—A passphrase that you can optionally specify in your Node.js project as an additional server-to-server authentication step. The recommended minimum length is 265 bits.

After completing these steps, the new Flex service should be visible in your Service Catalog.

Initializing a Node.js Project

Underneath, each Flex service is a Node.js project. Choose your preferred method to create the project. The following steps use NPM for that purpose.

Take these steps to initialize a Node.js project:

  1. Create a directory to contain your project files and enter it.
  2. Initialize a Node.js project using NPM:

     npm init

    This utility guides you through setting your Node.js project settings and finally writes a package.json file. Flex does not pose any particular requirements on the settings' values; accept the default values if you are in any doubt.

  3. Add the Flex SDK as a dependency in package.json:

     npm install kinvey-flex-sdk --save
  4. In the project directory, create an empty text file and name it after the entry point that you specified during the npm init execution.

    For example, if you accepted the default value, create a file called index.js.

Initializing the Flex SDK

After you have created the file structure needed for the project, you can start adding code. The Flex SDK is the only mandatory piece. Aside from it, you can require any npm module you need for your project.

To use the Flex SDK, require it in your project:

const sdk = require('kinvey-flex-sdk');

Then initialize the SDK to retrieve a reference to the backend service:

sdk.service((err, flex) => {
  // code goes here
});

When running locally, you can specify a host and port to listen on by passing an options object with an optional host and port. If no host and port are specified, localhost:10001 is used:

sdk.service({ host: 'flex-machine', port: 7777 }, (err, flex) => {
  // code goes here
});

Securing your Flex Service

For external Flex services, Kinvey recommends using HTTPS to ensure that all traffic is encrypted between Kinvey and the Flex service. In addition, Flex services can be secured by use of a shared secret which serves as server-to-server authentication.

All requests to a Flex service from Kinvey include the shared secret to prevent unauthorized access to the service. When configuring your service in the Kinvey Console, enter in a secure, random, strong shared secret (256-bit minimum recommended).

To enable the shared secret within your project code, pass the shared secret into the Flex SDK initialization method:

sdk.service({ sharedSecret: <my shared secret> }, (err, flex) => {
    // service code
})

If the shared secret is enabled in the Flex Service, the service will reject any request that does not include the shared secret key.

Running Your External FlexService

To run your FlexService, execute node . in the root of your project. Routes are:

For FlexData:

GET     /:serviceObject/                // Get all entities in a Service Object
GET     /:serviceObject/:id             // Get a single entity by id
GET     /:serviceObject/?{query}        // Get entities by query
POST    /:serviceObject/                // Create an entity
PUT     /:serviceObject/:id             // Update a service object entity
DELETE  /:serviceObject/                // Delete all service objects
DELETE  /:serviceObject/:id             // Delete a single entity by id
DELETE  /:serviceObject/?{query}        // Delete a service object by query
GET     /:serviceObject/_count          // Get a count of all records in the service object
GET     /:serviceObject/_count/?{query} // Get the count of a query result

For FlexFunctions:

POST    /_flexFunctions/:handlerName    // Execute the handler function
Got a question?