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

Git for working with Kinvey repositories
Node.js v6.x and NPM (node package manager). We recommend installing Node.js and NPM using NVM as it allows installation and usage of multiple versions of Node.js on the same machine.

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 run your server-side code.

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:

Log in to Kinvey Console.
Select the Service Catalog tab and click Add a service.
Select Flex and then External.
Complete the form and then click Save.
- Name—Arbitrary name for the service.
- Description—Optional details about the service.
- Scope/App—App or organization that will use the service.
  
  At this point, you will have a service created. The Console will start a new service environment for you, which is required for the service to be usable.
In the Connection Options tab of the service environment, enter a value for the following option or accept the default:
- 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.
Click Save to create the service environment and complete the service.

After completing these steps, the new Flex service appears 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:

Create a directory to contain your project files and enter it.
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.
Add the Flex SDK as a dependency in package.json:
```
 npm install kinvey-flex-sdk --save
```
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.

The Flex service will load this file first when executing your code.

Initializing the Flex SDK

After you create 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, it suggests a secure, randomly generated string. You can accept it or enter your own (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 specified within your project code, the service rejects any request that does not include the shared secret key.

For local testing, you can pass the shared secret in the X-Auth-Key HTTP header.

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

Mapping Flex Resources to Backend Features

A typical Flex service exposes a set of resources that you can use in your app. For example, a FlexData service would expose a data set, a FlexFunctions service would expose one or more callable handlers, and FlexAuth—a set of authentication-related handlers.

To use the resources exposed by your Flex service, you need to map them to the corresponding part of the Kinvey backend.

FlexData

Kinvey presents data coming from FlexData services as Kinvey collections. This way you can take advantage of the data abstraction provided by Kinvey and utilize the same APIs as you would when working with collections from the Kinvey Data Store.

Take these steps to map FlexData data to a Kinvey collection:

Log in to the Kinvey Console.
On the Apps tab, open an app environment.
Go to DATA > Collections and click Add a Collection.
Name the collection and click Save.

The Data source tab of the collection's Settings appears.
Select the Use a Data Service option.
Click the FlexData service that you created for your project.
From the Service Object drop-down list that appears, select the service object that you want to map to the collection.
Click Confirm.

FlexFunctions

Take these steps to map a FlexFunctions handler to a Collection Hook:

Log in to the Kinvey Console.
On the Apps tab, open an app environment.
Click BUSINESS LOGIC > Collection Hooks.
Click Add a Hook.
Select a Collection to attach the handler to.
Select a Hook type.
For Business Logic type, select Microservice and then click Create collection hook.
Select the FlexFunctions service that you created for your project.
From the Available handler functions drop-down list that appears, select the handler that you want to map to the hook.
Click Save changes.

Take these steps to map a FlexFunctions handler to a Custom Endpoint:

Log in to the Kinvey Console.
On the Apps tab, open an app environment.
Click BUSINESS LOGIC > Custom Endpoints
Click Add an Endpoint and give the ndpoint a name.
For Business Logic type, select Microservice and then click Create an endpoint.

FlexAuth

Take these steps to map a FlexAuth handler to a MIC service:

Log in to the Kinvey Console.
On the Apps tab, open an app environment.
Click IDENTITY > Mobile Identity Connect.
Click Add Auth Service.
Select Flex Runtime.
In the Kinvey Microservice Runtime section, select the FlexAuth service that you created for your project.
From the list that appears, select the handler that you want to map and click Save Changes.
Set up the rest of the MIC service settings and click Save Service.

Testing Locally

In production use, Kinvey injects a variety of context data in your Flex service code. Some Flex SDK modules require the data to work properly. You can simulate it for local testing through the use of HTTP headers.

See the full list of headers in the Flex API reference guide.

Guides