DEV Community: tashxii

Introduce Blockchain API of Cosmos SDK

tashxii — Wed, 01 Apr 2020 05:11:20 +0000

This post explains how to use and start Cosmos SDK - blockchain api.

What is Cosmos

Cosmos is a blockchain platform which is provided by Cosmos Network (Tendermint Inc).

https://cosmos.network/

What can be done by Cosmos SDK

With using Cosmos SDK, you can easily develop your product like a REST API server.
Cosmos SDK provides API which is written by Go language.

Actually, I could develop a REST API server by two days implementation in DeFi hackathon of San Francisco Blockchain Week 2019.

The following is a repository which I made in the hackathon.

https://github.com/tashxii/bor-bc-go

Build a REST API server

Starting point is to clone the following repository.

https://github.com/cosmos/sdk-tutorials/tree/master/nameservice

You can create REST API server and also store your own data in Cosmos Blockchain network.

I will introduce the important points when you develop a REST API server with using Cosmos SDK.

rest.go (x/borsevice/client/rest)

rest.go is an entry point of the definition of REST API.

You can define the corresponding of api url and actual function.

mux.Router is a router object of Cosmos SDK
you can set a combination of an api url and a function by "HandleFunc"
you can set a method type like "GET", "POST" and so on by "Methods"

// RegisterRoutes - Central function to define routes that get registered by the main application
func RegisterRoutes(cliCtx context.CLIContext, r *mux.Router, storeName string) {
    r.HandleFunc(fmt.Sprintf("/%s/prizes", storeName), namesHandler(cliCtx, storeName)).Methods("GET")
    r.HandleFunc(fmt.Sprintf("/%s/prizes", storeName), initPrizeHandler(cliCtx)).Methods("POST")
    r.HandleFunc(fmt.Sprintf("/%s/prizes", storeName), setPrizeHandler(cliCtx)).Methods("PUT")
    r.HandleFunc(fmt.Sprintf("/%s/prizes/{%s}", storeName, restName), resolveNameHandler(cliCtx, storeName)).Methods("GET")
    r.HandleFunc(fmt.Sprintf("/%s/prizes/{%s}/whois", storeName, restName), whoIsHandler(cliCtx, storeName)).Methods("GET")
    r.HandleFunc(fmt.Sprintf("/%s/prizes", storeName), deletePrizeHandler(cliCtx)).Methods("DELETE")
}

Define JSON format of a request

"rest" module - which can be import from "github.com/cosmos/cosmos-sdk/types/rest" - provides utilized function.

For example, you can see the use-case how to define JSON response and read and convert your own model in the following code.

"rest.BaseReq" struct is a base struct which you can add your own properties in JSON format.
"rest.ReadRESTReq" function can read HTTP request and convert a JSON request to in-memory object of your own struct.

type setPrizeReq struct {
    BaseReq       rest.BaseReq `json:"base_req"`
    Name          string       `json:"name"`
    Value         string       `json:"value"`
    Owner         string       `json:"owner"`
    Account       string       `json:"account"`
    Passphrase    string       `json:"passphrase"`
    Sequence      int64        `json:"sequence"`
    AccountNumber int64        `json:"accoutNumber"`
}

func setPrizeHandler(cliCtx context.CLIContext) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        var req setPrizeReq
        if !rest.ReadRESTReq(w, r, cliCtx.Codec, &req) {
            rest.WriteErrorResponse(w, http.StatusBadRequest, "failed to parse request")
            return
        }
    (snip)

Write your own process of Cosmos blockchain

After reading JSON request, you can implement your own process of Cosmos blockchain.

The following code is an example to do create a transaction and sign it and then broadcast to the blockchain network.

// WriteGenerateStdTxResponse writes response for the generate only mode.
func WriteGenerateStdTxResponse(w http.ResponseWriter, cliCtx context.CLIContext,
    br rest.BaseReq, msgs []sdk.Msg, req setPrizeReq) {
    gasAdj, ok := rest.ParseFloat64OrReturnBadRequest(w, br.GasAdjustment, flags.DefaultGasAdjustment)
    if !ok {
        return
    }

    simAndExec, gas, err := flags.ParseGas(br.Gas)
    if err != nil {
        rest.WriteErrorResponse(w, http.StatusBadRequest, err.Error())
        return
    }

    txBldr := types.NewTxBuilder(
        utils.GetTxEncoder(cliCtx.Codec), br.AccountNumber, br.Sequence, gas, gasAdj,
        br.Simulate, br.ChainID, br.Memo, br.Fees, br.GasPrices,
    )

    if br.Simulate || simAndExec {
        if gasAdj < 0 {
            rest.WriteErrorResponse(w, http.StatusBadRequest, errInvalidGasAdjustment.Error())
            return
        }

        txBldr, err = utils.EnrichWithGas(txBldr, cliCtx, msgs)
        if err != nil {
            rest.WriteErrorResponse(w, http.StatusInternalServerError, err.Error())
            return
        }

        if br.Simulate {
            rest.WriteSimulationResponse(w, cliCtx.Codec, txBldr.Gas())
            return
        }
    }

    stdMsg, err := txBldr.BuildSignMsg(msgs)
    if err != nil {
        rest.WriteErrorResponse(w, http.StatusBadRequest, err.Error())
        return
    }

    transactionStdTx := types.NewStdTx(stdMsg.Msgs, stdMsg.Fee, nil, stdMsg.Memo)

    // Create cdc
    cdc := cliCtx.Codec

    // Sign Tx
    signedStdTx, err := signTx(cdc, transactionStdTx, req.Account, req.Account, req.Passphrase, req.Sequence, req.AccountNumber)
    if err != nil {
        rest.WriteErrorResponse(w, http.StatusInternalServerError, err.Error())
        return
    }

    // TODO Broadcast Tx
    err = broadcastTx(cdc, signedStdTx)
    if err != nil {
        rest.WriteErrorResponse(w, http.StatusInternalServerError, err.Error())
        return
    }
    output, err := cliCtx.Codec.MarshalJSON(signedStdTx)
    if err != nil {
        rest.WriteErrorResponse(w, http.StatusInternalServerError, err.Error())
        return
    }

    w.Header().Set("Content-Type", "application/json")
    if _, err := w.Write(output); err != nil {
        log.Printf("could not write response: %v", err)
    }

    return
}

Create a transaction

Cosmos SDK provides a builder of transaction called as "types.TxBuilder".

you can create a builder by "types.NewTxBuilder" function.
a transaction object can be generated by "txBldr.BuildSignMsg" function.

Sign and broadcast a transaction

"signTx" & "broadcast" functions are not provided as Cosmos REST API.
They are reused from Cosmos CLI SDK and converted by me to fit REST API in the hackathon.

If you have further interesting about these two functions.
Please see the following codes.

https://github.com/tashxii/bor-bc-go/blob/dd3258bd338df23a65432cd4eed2007091d763a9/x/borservice/client/rest/extend_rest.go#L95-L156

How to integrate REST API in React application

tashxii — Mon, 30 Mar 2020 21:42:26 +0000

This post describes the way to integrate REST API to a React application.
The sample codes are based on the source code when I joined DeveloperWeek 2020 hackathon.

https://www.developerweek.com/events/hackathon/

Fetch API

Fetch API is standard API to access HTTP resources and it is similar to XMLHttpRequest API.
For details, see the following reference.

https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

Common class for API

The following code is a common class named as "APICommon" to call get, post, put and delete method for REST API.

Basically, this class has get, post, put and delete functions, each function is corresponding to each http method.

let setting = undefined
let endPoint = ""
const mode = "cors"
const credential = "omit"
const headers = new Headers({
  "Content-type": "application/json",
})

export default class ApiCommon {
  static Method = {
    GET: "GET",
    POST: "POST",
    PUT: "PUT",
    DELETE: "DELETE",
  }

  static init(serverSetting) {
    setting = serverSetting
    endPoint = `${setting.url}/${setting.base}`
  }

  static async get(path) {
    return doFetch(
      getApiUrl(path),
      getOption()
    )
  }

  static async post(path, request) {
    return doFetch(
      getApiUrl(path),
      getUpdateOption(ApiCommon.Method.POST, request)
    )
  }

  static async put(path, request) {
    return doFetch(
      getApiUrl(path),
      getUpdateOption(ApiCommon.Method.PUT, request)
    )
  }

  static async delete(path, request) {
    return doFetch(
      getApiUrl(path),
      getUpdateOption(ApiCommon.Method.DELETE, request)
    )
  }
}

const getApiUrl = (path) => {
  const apiUrl = `${endPoint}${path}`
  return apiUrl
}

const getOption = () => {
  const option = {
    method: ApiCommon.Method.GET,
    mode: mode,
    credential: credential,
    headers: headers,
  }
  return option
}

const getUpdateOption = (method, request) => {
  const option = {
    method: method,
    mode: mode,
    credential: credential,
    headers: headers,
    body: JSON.stringify(request),
  }
  return option
}

const doFetch = async (path, option) => {
  let ok = false
  let status = -1
  console.debug("API-request:", path, option)
  return await fetch(path, option)
    .then(response => {
      ok = response.ok
      status = response.status
      return response.text()
    })
    .then(text => {
      const json = text !== "" ? JSON.parse(text) : {}
      console.debug("API-response:", path, status, { json })
      return { ok, status, json }
    })
    .catch(error => {
      console.debug("API-error:", path, { error })
      throw error
    })
}

How to use common API class

Initialize

Call to "ApiCommon.initalize" method in your entry point jsx file like App.jsx.

URL and REST API base part are configured in a json file like "setting.json".

{
  (snip)
  "server": {
    "url": "http://localhost:7000",
    "base": "detra"
  }
  (snip)
}

Wrapper class for a resource of REST API server

The following code is an example to access "User" resource of REST API server.

Each function name is corresponding to one REST API name.
Every function is "async" function by using "await"
To use APICommon is just easy like below.
- login ... post method to login. ApiCommon.post("/login", request)
- create ... post method to create user. ApiCommon.post("/users", request)
- list ... get method to retrieve user list. ApiCommon.get("/users")

import ApiCommon from "./apiCommon"

export default class UserApi {
  static login = async (request) => {
    return ApiCommon.post("/login", request)
  }

  static create = async (request) => {
    return ApiCommon.post("/users", request)
  }

  static list = async () => {
    return ApiCommon.get("/users")
  }

  static get = async (userId) => {
    return ApiCommon.get(`/users/${userId}`)
  }

  static update = async (userId, request) => {
    return ApiCommon.put(`/users/${userId}`, request)
  }

  static delete = async (userId) => {
    return ApiCommon.delete(`/users/${userId}`, {})
  }
}

Helpful tools for test

I introduce two tools for developing REST API.

Advanced REST Client

"Advanced REST Client" is a GUI tool for REST API server.

https://advancedrestclient.com

You can test your and 3rd party REST API with using GUI.

Json Utils - online json to code converter

Json Utils is an online converter site from json to several programing language.

https://www.jsonutils.com/

You can generate class/object source code from input json format.
It is also helpful to develop from sample json response.

API World Hackathon Report No.2 - DocuSign Clickwrap with React

tashxii — Thu, 28 Nov 2019 01:55:37 +0000

This is a report of TIS Ventures Inc's software engineer who joined API world hackathon 2019.
In this post, I would like to explain how to integrate DocuSign Clickwrap API into a React appliction.

What is API World

"API world" is the event regarding API as described on their own page as below;

the world's largest vendor-neutral API conference and expo

https://apiworld.co/

DocuSign Challenge #2

We chose the following challenge which is about "Clickwrap" API of DocuSign.
As you may know, DocuSign is a company that provides electronic-signature service for documents.

Challenge #2: DocuSign - Implement "Click to Agree" Functionality using the DocuSign Click API (2)

Clickwrap agreements are everywhere. Do you recall those "terms of service" agreements you must scroll through and click to agree? The DocuSign Click API provides an extremely lightweight interface through which to create, manage, and modify clickwrap agreements. To implement a clickwrap in your application within 10 minutes

https://developers.docusign.com/click-api/guides/

Clickwrap has a capability to register user's "terms and service" document on the DocuSign server and integrate to download and show it with "Agree" button in user's web site.

As result, we got the 1st prize 🏆 for this challenge.

https://devpost.com/software/eagles-challenge-2-docusign

How to integrate DocuSign Clickwrap API into React application

DocuSign provides the function to generate javascript code snippet to call "Clickwrap" API.
It is easy to integrate "normal" web site, but our application is built by React.

The following steps show how to integrate it into a React application.

1) import docusign-click.js in index.html of React application

<script src="https://demo.docusign.net/clickapi/sdk/latest/docusign-click.js"></script>

2) Create new React component as below.
But this does not work correctly due to the "pit fall" of "dangerouslySetInnerHTML" of React component.
The content of 'clickwrapCode' variable is a snippet code which is given by "Clickwrap" management page.

import React, { Component } from "react"
import uuid from "uuid"
import InnerHTML from "dangerously-set-inner-html"
const clickwrapCode = (clientUserId) => `
<div id="ds-clickwrap"></div>
<script>docuSignClick.Clickwrap.render({
environment: 'https://demo.docusign.net',
accountId: 'bra-bra',
clickwrapId: 'bra-bra-bra',
clientUserId: '${clientUserId}'
}, '#ds-clickwrap');</script>
`
class TermsOfConditionsView extends Component {
  render() {
    return <div dangerouslySetInnerHTML={{__html: clickwrapCode(uuid.v4())}}/>
  }
}
export default TermsOfConditionsView

3) Pit fall of "dangerouslySetInnerHTML"
The above component shows the contents but its script is not executed automatically.

The contents of script tag is never evaluated by design of React component.

For details, see "dangerouslysetinnerhtml react" - https://code-examples.net/en/q/21f7059

4) Evaluate script tag by using "dangerously-set-inner-html" component
The following component solved this "dangerouslySetInnerHTML" problem.

It could be used instead of div tag.

"dangerously-set-inner-html" https://www.npmjs.com/package/dangerously-set-inner-html

5) Finally, the component code will be as below;

import React, { Component } from "react"
import uuid from "uuid"
import InnerHTML from "dangerously-set-inner-html"
const clickwrapCode = (clientUserId) => `
<div id="ds-clickwrap"></div>
<script>docuSignClick.Clickwrap.render({
environment: 'https://demo.docusign.net',
accountId: 'bra-bra',
clickwrapId: 'bra-bra-bra',
clientUserId: '${clientUserId}'
}, '#ds-clickwrap');</script>
`
class TermsOfConditionsView extends Component {
  render() {
    return <InnerHTML html={clickwrapCode(uuid.v4())}/>
  }
}
export default TermsOfConditionsView

I hope this knowledge will be helpful those who use DocuSign with React.