#Creating API Servers

A common use-case for a module is that you process some data from within core and want to make use of that data with an external application. The easiest way to do this is through an HTTP server that exposes an API from which you request the data.

#Step 0: Create A New Module From A Template

To create a new module from a template follow this simple guide:

After you have created the module and adjusted basic properties (name, structure, dependencies) we can start to add custom functionalities, like adding a HTTP server.

You can also use our template project with HTTP server implementation already done and create a new module from it.

github.com

GitHub - learn-ark/dapp-core-module-http-server-template: ARK Core Module Template With Reusable HTTP Server Implementation

ARK Core Module Template With Reusable HTTP Server Implementation - GitHub - learn-ark/dapp-core-module-http-server-template: ARK Core Module Template With Reusable HTTP Server Implementation

#Step 1: Adding core-http-utils Dependency

Steps 1 and 2 are basic explanation of needed packages and implementation decisions for the HTTP server module template we are using. This is a recommended read if you want to understand the basic server mechanics and how to add it to you existing modules.

As you’ve learned in How to write a Core Modules you will need to install the required dependencies. For our example we will use we need the core-http-utils package which you can install with the following command:

1cd your-module-folder
2lerna add @arkecosystem/core-http-utils --scope=@vendor/demo-plugin

This will add a core-http-utils package dependency to our module.

#Step 2: Implement a HTTP Server Inside dApp Module

Now that core-http-utils is installed we can get started with starting our HTTP server, which is fairly simple.

This example will register a server with a single endpoint at http://localhost:5003/ where localhost is the host and 5003 the port. When you run curl http://localhost:5003/ you should get Hello ARKies as response.

To create our server we need to import the following packages from core-http-utils:

1import { createServer, mountServer } from "@arkecosystem/core-http-utils";
2import Hapi from "@hapi/hapi";

To start the server with predefined configuration we call the createServer and mountServer methods.

1await createServer(options);
2await Server.registerRoutes("HTTP", this.http);
3await mountServer(`Custom HTTP Public ${name.toUpperCase()} API`, server);

Below is the whole server.ts file that handles the creation and mounting logic and plugin.ts that starts/stops the HTTP server. Looking at the tabs, you can see the full implementation of the custom HTTP server logic and how it relates to the overall dApp creation module logic. Also note the registerRoutes method where you can custom routes.

plugin.ts

 1import { Container, Logger } from "@arkecosystem/core-interfaces";
 2import { defaults } from "./defaults";
 3import { Server } from "./server";
 4 
 5export const plugin: Container.IPluginDescriptor = {
 6    pkg: require("../package.json"),
 7    defaults,
 8    alias: "core-custom-server-example",
 9    async register(container: Container.IContainer, options) {
10        container.resolvePlugin<Logger.ILogger>("logger").info("Starting dApp");
11 
12        const server = new Server(options);
13        await server.start();
14 
15        return server;
16    },
17 
18    async deregister(container: Container.IContainer, options) {
19        await container.resolvePlugin<Server>("core-custom-server-example").stop();
20    },
21};

defaults

1export const defaults = {
2    enabled: true,
3    host: "0.0.0.0",
4    port: 5003,
5};

server.ts

 1export class Server {
 2    private logger = app.resolvePlugin<Logger.ILogger>("logger");
 3 
 4    private http: any;
 5 
 6    public constructor(private readonly config: any) {
 7        this.config = config;
 8    }
 9 
10    public async start(): Promise<void> {
11        const options = {
12            host: this.config.host,
13            port: this.config.port,
14        };
15 
16        if (this.config.enabled) {
17            this.http = await createServer(options);
18            this.http.app.config = this.config;
19 
20            await Server.registerRoutes("HTTP", this.http);
21        }
22 
23        // TODO: add SSL support. See plugin `core/packages/core-api` for more information
24    }
25 
26    public async stop(): Promise<void> {
27        if (this.http) {
28            this.logger.info(`Stopping Custom HTTP Server`);
29            await this.http.stop();
30        }
31    }
32 
33    public async restart(): Promise<void> {
34        if (this.http) {
35            await this.http.stop();
36            await this.http.start();
37        }
38    }
39 
40    public instance(type: string): Hapi.Server {
41        return this[type];
42    }
43 
44    private static async registerRoutes(name: string, server: Hapi.Server): Promise<void> {
45        server.route({
46            method: "GET",
47            path: "/",
48            handler() {
49                return { data: "Hello ARKies!" };
50            },
51        });
52 
53        await mountServer(`Custom HTTP Public ${name.toUpperCase()} API`, server);
54    }
55}

#Implementing Route Handlers

Adding more routes and handlers within the same file would make code unreadable. That is why we must split the logic into route registrations and implementations. The file handlers.ts inside the template module servers serves as an example on how to achieve this. For example we register a route in the server.ts with this line (add this line to registerRoutes method: line 52 in file server.ts above, just before the mountServer call):

1// source: https://github.com/learn-ark/dapp-core-module-http-server-template/blob/master/src/server.ts#L63
2server.route([{ method: "GET", path: "/config", ...handlers.config }]);

The above registered route is implemented with in the handler.ts file:

handler.ts

 1import { app } from "@arkecosystem/core-container";
 2import { Plugins } from "@arkecosystem/core-utils";
 3 
 4export const config = {
 5    async handler() {
 6        const appConfig = app.getConfig();
 7 
 8        return {
 9            data: {
10                version: app.getVersion(),
11                network: {
12                    version: appConfig.get("network.pubKeyHash"),
13                    name: appConfig.get("network.name"),
14                    nethash: appConfig.get("network.nethash"),
15                    explorer: appConfig.get("network.client.explorer"),
16                    token: {
17                        name: appConfig.get("network.client.token"),
18                        symbol: appConfig.get("network.client.symbol"),
19                    },
20                },
21                plugins: Plugins.transformPlugins(appConfig.config.plugins),
22            },
23        };
24    },
25    config: {
26        cors: true,
27    },
28};

By using this approach it is much easier to split and manage your API code. Also check our official core-api plugin to learn more about our API and best practices.

#Step 3: Load The Module Within Network Configuration

We already learned how to load the new module within selected network configuration. All we have to do is edit the plugin.js file and add our new module name to the list.

#Step 3.1: Add New Module To The Network plugins.js file

Go here for detailed explanation on how to achieve this.

#Step 3.2: Start Your dApp

Your implemented dApp application leaves and works from the ARK Core blockchain node as an independent Core module.

Now Go And Start You Local Testnet Blockchain with the new module enabled by following this guide!

#Step 4: Test Your New API Server

When Core is started you should see the dApp starting and enabling HTTP server messages in the core.log, similar to the display below:

1... a lot of text
2[2019-12-09 08:59:31.680] INFO : Starting dApp
3[2019-12-09 08:59:31.685] INFO : Custom HTTP Public HTTP API Server running at: http://0.0.0.0:5003
4... a lot of text :)

Looking at the source code from the template (file server.ts ) we registered two endpoints:

• GET 0.0.0.0:5003/
• GET 0.0.0.0:5003/config

The default greeting endpoint was registered and implemented directly from the method in server.ts .

The configuration endpoint was registered from the server.ts , but the implementation is in the handlers.ts file. We have split the logic into route registrations and actual implementations.

Continue to play around and start implementing your own application, supported by custom API, all packed within the ARK Core module concept, and still fully compatible with our bridgechain ecosystem.

In the next part, we will learn how to listen to blockchain and share the information via API. We will continue to work on this example.