Overview

Skill Level: Intermediate

This recipe shows you how integrate Hyperledger Composer with a client application using a front-end framework like Angular.JS. In doing so, you learn how to work with Hyperledger Composer RESTful API.

Ingredients

To follow and complete this recipe, you need to have good knowledge of blockchain, Hyperledger transactions, JavaScript as well as basic knowledge of Linux and Angular.JS.

Step-by-step

  1. Hyperledger Composer Overview

    Hyperledger Composer is a set of collaboration tools for business owners and developers that make it easy to write chaincode (also known as smart contracts) for Hyperledger Fabric and Decentralized Applications (DApps). With Composer, you can quickly build Proof-of-Concept and deploy chaincode to the blockchain in a short amount of time.

    We implemented all the models, transactions, and query functions in our previous recipe or Blockchain Hyperledger Composer and Playground Development Components. Then, we finished deploying the business network archive to the blockchain network. Once you deploy the application to the Hyperledger Fabric network, how do you integrate it with your client application? One solution would be to use the Hyperledger Composer REST server.

    To better understand and follow this recipe, reading Hyperledger Composer business network and development requirements is highly recommended. Also, for those who are not familiar with Hyperledger project, reading Intro to Hyperledger Family and Hyperledger Blockchain Ecosystem and Hyperledger Design Philosophy and Framework Architecture articles are strongly recommended beforehand.

  2. How Hyperledger Composer REST Works

    The Hyperledger Composer REST server can be used to generate a Swagger REST endpoint API from a deployed Hypeledger Fabric business network. The REST server utilizes the LoopBack and converts the business network model into an open API definition. An authenticated client calls the REST server via these endpoint APIs to interact with a blockchain. Each invoked transaction must be signed by a certificate. The REST server starts this identity and signs all transactions with this. At runtime, the REST server implements Create, Read, Update, and Delete (CRUD) operations to manipulate the state of assets and participants and allow transactions to be submitted or retrieved with queries.

  3. Launch Composer REST Server

    To launch the Composer REST server, simply type the following:
    composer-rest-server
    The Unix Terminal will ask you a few questions about your business network:
    Blockchain Hyperledger Composer Restful API and Angular.JS 1

     

    Once the server starts up, the web server will be listening at http://localhost:3000 or
    http://yourserverIP:3000.

    You can browse your REST API at http://localhost:3000/explorer:
    Blockchain Hyperledger Composer Restful API and Angular.JS 2

     

    Browse around and explore the REST API. The page shows different endpoints, including all assets, participants, and transactions defined in the model and logic.js. The query API from queries.qry is also displayed on the page. You can test a simple query within the Explorer.
    At this point, we can start to build a frontend application to interact with the generated REST API. We will explore a few options for this.

  4. Build Frontend Application with Angular.JS

    Yeoman generators support generating an Angular-based web application skeleton via the hyperledger-composer module. The Composer REST server needs to be running and connected to the Hyperledger Fabric blockchain. The Yeoman Angular command needs to run in the same directory as the .bna file. Execute the following commands:
    1. Open a new Terminal and navigate to ~/farmaTrace/farmatrace-network using the following command:

    yo hyperledger-composer

    2. Enter the required project information and business network card:
    Blockchain Hyperledger Composer Restful API and Angular.JS 3

     

    3. This will generate an Angular application via the Yeoman tool. Navigate to the farmatrace-ng directory and you will see that the following Angular files have been generated:
    Blockchain Hyperledger Composer Restful API and Angular.JS 4

     

    4. Make sure you have installed all angular-related packages:

    npm install -g typings
    npm install -g bower
    npm install -g @angular/cli
    Start angular application by enter command:
    ng serve

    If you run on AWS cloud server, you can run this command:
    ng serve –host your_private_IP –port 4200

    You may get an invalid host header message when you run Angular in the cloud server. It is an Angular CLI-related issue as seen at https://github.com/angular/angular-cli/issues/6070#issuecomment-298208974. You can fix this by editing service.js in node_modules/webpack-dev-
    server/lib/Server.js (line 425); change it to return true;

    5. The previous step will bring up the Angular client server. Once the server is up, you can open http://localhost:4200 or http://yourserverip:4200:
    Blockchain Hyperledger Composer Restful API and Angular.JS 5

     

    6. From here, you can start to update your Angular file to build your web application for farmatrace:

    Blockchain Hyperledger Composer Restful API and Angular.JS 6

  5. Putting Things Together

    The Yeoman Hyperledger Composer tool generates a proxy configuration and connects to the Composer REST server:
    function getTarget() {

    if (process.env.REST_SERVER_URLS) {

    const restServerURLs = JSON.parse(process.env.REST_SERVER_URLS); const restServerURL = restServerURLs[‘farmatrace-network’];‚Ķ

    }
    …

    return ‘http://localhost:3000’;

    }

    It reads business-network meta-information, then generates the org.hyperledger.composer.system.ts typescript file. This file contains the definition of asset, transaction, and participant, as seen in the following code block:
    export namespace org.hyperledger.composer.system{ export  abstract class Registry extends Asset {
    registryId: string;

    name: string;

    type: string;

    system: boolean;

    }

    ..

    It also generates org.packt.farmatrace.ts, which defines all the classes of asset, participant, and transactions from org.hyperledger.composer.system.ts:

    import {Participant} from ‘./org.hyperledger.composer.system’; import {Transaction} from ‘./org.hyperledger.composer.system’;

    1. export namespace org.packt.farmatrace{

     

    export class Manufacturer extends Participant { manufacturerId: string;

    entityInfo: Entity;

    }

    The data.service.ts file in the Angular application will query or update the transactions API that was explored by Composer REST server:

    export class DataService<Type> {

    constructor(private http: Http) {

    this.actionUrl = ‘/api/’;

    this.headers = new Headers();

    this.headers.append(‘Content-Type’, ‘application/json’);

    this.headers.append(‘Accept’, ‘application/json’);

    }

    public getAll(ns: string): Observable<Type[]> { console.log(‘GetAll ‘ + ns + ‘ to ‘ + this.actionUrl + ns); return this.http.get(`${this.actionUrl}${ns}`)

    .map(this.extractData)

    .catch(this.handleError);

    }

    After successfully finishing this tutorial along with previous recipes, you know how to build and integrate blockchain applications using Hyperledger Composer. The next step is to learn how to install Hyperledger Fabric and its components and build smart contracts with Hyperledger Fabric.

    This article is written in collaboration with Brian Wu who is a senior Hyperledger instructor at Coding Bootcamps school in Washington DC.

Join The Discussion