Hyperledger Fabric provides software development kits/SDKs to help developers access the fabrics network and chain codes deployed on the network, but Hyperledger Fabric does not officially provide an easy-to-use REST API access interface. In this tutorial, we will learn how to use Hyperledger Fabric's SDK to develop a REST API server.
1. Overview of system structure
Recommendations: H..Fabric Java Development Tutorial | H..Fabric Nodejs Development Tutorial
The system consists of two physical nodes:
- Fabric node: Runs First Network in the Fabric example and instantiates the Fabcar chain code
- API Server Node: Run REST API Server code for external access
Here are two instances of nodes deployed on AWS:
First install the hyperledger fabric with reference to the official documentation.
Then run the script fabcar/startFabric.sh:
cd fabric-samples/fabcar ./startFabric.sh
After the above script runs, we get a functioning Hipperledger Fabric network (the well-known demonstration network First Network), which consists of two agencies/four peer nodes, the channel is mychannel, and the chain code Fabcar is installed on all four peer nodes and activated on mychannel.There are 10 vehicle records in the ledger, which is the result of calling the initLedger method of the contract.
Now we'll prepare the identity data for the REST API Server.Create a user identity user1 using fabcar/javascript, which we will use in the REST API Server:
cd javascript npm install node enrollAdmin.js node registerUser.js ls wallet/user1
The results are as follows:
Now Rest API Server has everything it needs:
- Connection profile for org1: first-network/connection-org1.json
- Node.js package file: fabcar/package.json
- User1 Identity Wallet: fabcar/javascript/wallet/user1/
We'll copy these data files to the Rest API Server later.
2. Rest API Server Design
We use ExressJS to develop API services and code from query.js and invoke.js to implement logic for interacting with fabric s.The API is designed as follows:
- GET/api/queryallcars: Return all vehicle records
- GET/api/query/CarID: Returns the vehicle record with the specified ID
- POST/api/addcar/: Add a new vehicle record
- PUT/api/changeowner/CarID: Modify vehicle record with specified ID
3. Rest API Server Code Implementation
The apiserver.js code is as follows:
var bodyParser = require('body-parser'); var app = express(); app.use(bodyParser.json()); // Setting for Hyperledger Fabric const { FileSystemWallet, Gateway } = require('fabric-network'); const path = require('path'); const ccpPath = path.resolve(__dirname, '.', 'connection-org1.json'); app.get('/api/queryallcars', async function (req, res) { try { // Create a new file system based wallet for managing identities. const walletPath = path.join(process.cwd(), 'wallet'); const wallet = new FileSystemWallet(walletPath); console.log(`Wallet path: ${walletPath}`); // Check to see if we've already enrolled the user. const userExists = await wallet.exists('user1'); if (!userExists) { console.log('An identity for the user "user1" does not exist in the wallet'); console.log('Run the registerUser.js application before retrying'); return; } // Create a new gateway for connecting to our peer node. const gateway = new Gateway(); await gateway.connect(ccpPath, { wallet, identity: 'user1', discovery: { enabled: true, asLocalhost: false } }); // Get the network (channel) our contract is deployed to. const network = await gateway.getNetwork('mychannel'); // Get the contract from the network. const contract = network.getContract('fabcar'); // Evaluate the specified transaction. // queryCar transaction - requires 1 argument, ex: ('queryCar', 'CAR4') // queryAllCars transaction - requires no arguments, ex: ('queryAllCars') const result = await contract.evaluateTransaction('queryAllCars'); console.log(`Transaction has been evaluated, result is: ${result.toString()}`); res.status(200).json({response: result.toString()}); } catch (error) { console.error(`Failed to evaluate transaction: ${error}`); res.status(500).json({error: error}); process.exit(1); } }); app.get('/api/query/:car_index', async function (req, res) { try { // Create a new file system based wallet for managing identities. const walletPath = path.join(process.cwd(), 'wallet'); const wallet = new FileSystemWallet(walletPath); console.log(`Wallet path: ${walletPath}`); // Check to see if we've already enrolled the user. const userExists = await wallet.exists('user1'); if (!userExists) { console.log('An identity for the user "user1" does not exist in the wallet'); console.log('Run the registerUser.js application before retrying'); return; } // Create a new gateway for connecting to our peer node. const gateway = new Gateway(); await gateway.connect(ccpPath, { wallet, identity: 'user1', discovery: { enabled: true, asLocalhost: false } }); // Get the network (channel) our contract is deployed to. const network = await gateway.getNetwork('mychannel'); // Get the contract from the network. const contract = network.getContract('fabcar'); // Evaluate the specified transaction. // queryCar transaction - requires 1 argument, ex: ('queryCar', 'CAR4') // queryAllCars transaction - requires no arguments, ex: ('queryAllCars') const result = await contract.evaluateTransaction('queryCar', req.params.car_index); console.log(`Transaction has been evaluated, result is: ${result.toString()}`); res.status(200).json({response: result.toString()}); } catch (error) { console.error(`Failed to evaluate transaction: ${error}`); res.status(500).json({error: error}); process.exit(1); } }); app.post('/api/addcar/', async function (req, res) { try { // Create a new file system based wallet for managing identities. const walletPath = path.join(process.cwd(), 'wallet'); const wallet = new FileSystemWallet(walletPath); console.log(`Wallet path: ${walletPath}`); // Check to see if we've already enrolled the user. const userExists = await wallet.exists('user1'); if (!userExists) { console.log('An identity for the user "user1" does not exist in the wallet'); console.log('Run the registerUser.js application before retrying'); return; } // Create a new gateway for connecting to our peer node. const gateway = new Gateway(); await gateway.connect(ccpPath, { wallet, identity: 'user1', discovery: { enabled: true, asLocalhost: false } }); // Get the network (channel) our contract is deployed to. const network = await gateway.getNetwork('mychannel'); // Get the contract from the network. const contract = network.getContract('fabcar'); // Submit the specified transaction. // createCar transaction - requires 5 argument, ex: ('createCar', 'CAR12', 'Honda', 'Accord', 'Black', 'Tom') // changeCarOwner transaction - requires 2 args , ex: ('changeCarOwner', 'CAR10', 'Dave') await contract.submitTransaction('createCar', req.body.carid, req.body.make, req.body.model, req.body.colour, req.body.owner); console.log('Transaction has been submitted'); res.send('Transaction has been submitted'); // Disconnect from the gateway. await gateway.disconnect(); } catch (error) { console.error(`Failed to submit transaction: ${error}`); process.exit(1); } }) app.put('/api/changeowner/:car_index', async function (req, res) { try { // Create a new file system based wallet for managing identities. const walletPath = path.join(process.cwd(), 'wallet'); const wallet = new FileSystemWallet(walletPath); console.log(`Wallet path: ${walletPath}`); // Check to see if we've already enrolled the user. const userExists = await wallet.exists('user1'); if (!userExists) { console.log('An identity for the user "user1" does not exist in the wallet'); console.log('Run the registerUser.js application before retrying'); return; } // Create a new gateway for connecting to our peer node. const gateway = new Gateway(); await gateway.connect(ccpPath, { wallet, identity: 'user1', discovery: { enabled: true, asLocalhost: false } }); // Get the network (channel) our contract is deployed to. const network = await gateway.getNetwork('mychannel'); // Get the contract from the network. const contract = network.getContract('fabcar'); // Submit the specified transaction. // createCar transaction - requires 5 argument, ex: ('createCar', 'CAR12', 'Honda', 'Accord', 'Black', 'Tom') // changeCarOwner transaction - requires 2 args , ex: ('changeCarOwner', 'CAR10', 'Dave') await contract.submitTransaction('changeCarOwner', req.params.car_index, req.body.owner); console.log('Transaction has been submitted'); res.send('Transaction has been submitted'); // Disconnect from the gateway. await gateway.disconnect(); } catch (error) { console.error(`Failed to submit transaction: ${error}`); process.exit(1); } }) app.listen(8080);
The query.js and invoke.js of the original fabcar are modified in the code as follows:
- ccpPath is modified to the current directory because we want to use the connection profile connection-org1.json under the same path
- In the gateway.connect call, modify the option discovery.asLocalhost to false
4. Connection profile for Rest API Server
API services rely on connection profiles to properly connect to the fabric s network.The file connection-org1.json can be accessed directly from Get on the fabric network:
{ "name": "first-network-org1", "version": "1.0.0", "client": { "organization": "Org1", "connection": { "timeout": { "peer": { "endorser": "300" } } } }, "organizations": { "Org1": { "mspid": "Org1MSP", "peers": [ "peer0.org1.example.com", "peer1.org1.example.com" ], "certificateAuthorities": [ "ca.org1.example.com" ] } }, "peers": { "peer0.org1.example.com": { "url": "grpcs://localhost:7051", "tlsCACerts": { "pem": "-----BEGIN CERTIFICATE-----\nMIICVjCCAf2gAwIBAgIQEB1sDT11gzTv0/N4cIGoEjAKBggqhkjOPQQDA jB2MQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMNU2FuIEZy\nYW5jaXNjbzEZMBcGA1UEChMQb3JnMS5leGF tcGxlLmNvbTEfMB0GA1UEAxMWdGxz\nY2Eub3JnMS5leGFtcGxlLmNvbTAeFw0xOTA5MDQwMjQzMDBaFw0yOTA5MDEwMjQz\nMDBaMHYxCzAJB gNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQH\nEw1TYW4gRnJhbmNpc2NvMRkwFwYDVQQKExBvcmcxLmV4YW1wbGUuY29tM R8wHQYD\nVQQDExZ0bHNjYS5vcmcxLmV4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0D\nAQcDQgAEoN0qd5hM2SDfvGzNjTCXuQqyk+X K4VISa16/y9iXBPpa0onyAXJuv7T0\noPf+mh3T7/g8uYtV2bwTpT2XFO3Q6KNtMGswDgYDVR0PAQH/BAQDAgGmMB0GA1Ud\nJQQWMBQGCCsGA QUFBwMCBggrBgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1Ud\nDgQiBCCalpyChmrLtpgOll6TVmlMOO/2iiyI2PadNPsIYx51mTAKBggqh kjOPQQD\nAgNHADBEAiBLNoAYWe9LvoxxBxl3sUM64kl7rx6dI3JU+dJG6FRxWgIgCu1ONEyp\nfux9lZWr6gcrIdsn/8fQuWiOIbAgq0HSr60 =\n-----END CERTIFICATE-----\n" }, "grpcOptions": { "ssl-target-name-override": "peer0.org1.example.com", "hostnameOverride": "peer0.org1.example.com" } }, "peer1.org1.example.com": { "url": "grpcs://localhost:8051", "tlsCACerts": { "pem": "-----BEGIN CERTIFICATE-----\nMIICVjCCAf2gAwIBAgIQEB1sDT11gzTv0/N4cIGoEjAKBggqhkjOPQQDA jB2MQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMNU2FuIEZy\nYW5jaXNjbzEZMBcGA1UEChMQb3JnMS5leGF tcGxlLmNvbTEfMB0GA1UEAxMWdGxz\nY2Eub3JnMS5leGFtcGxlLmNvbTAeFw0xOTA5MDQwMjQzMDBaFw0yOTA5MDEwMjQz\nMDBaMHYxCzAJB gNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQH\nEw1TYW4gRnJhbmNpc2NvMRkwFwYDVQQKExBvcmcxLmV4YW1wbGUuY29tM R8wHQYD\nVQQDExZ0bHNjYS5vcmcxLmV4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0D\nAQcDQgAEoN0qd5hM2SDfvGzNjTCXuQqyk+X K4VISa16/y9iXBPpa0onyAXJuv7T0\noPf+mh3T7/g8uYtV2bwTpT2XFO3Q6KNtMGswDgYDVR0PAQH/BAQDAgGmMB0GA1Ud\nJQQWMBQGCCsGA QUFBwMCBggrBgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1Ud\nDgQiBCCalpyChmrLtpgOll6TVmlMOO/2iiyI2PadNPsIYx51mTAKBggqh kjOPQQD\nAgNHADBEAiBLNoAYWe9LvoxxBxl3sUM64kl7rx6dI3JU+dJG6FRxWgIgCu1ONEyp\nfux9lZWr6gcrIdsn/8fQuWiOIbAgq0HSr60 =\n-----END CERTIFICATE-----\n" }, "grpcOptions": { "ssl-target-name-override": "peer1.org1.example.com", "hostnameOverride": "peer1.org1.example.com" } } }, "certificateAuthorities": { "ca.org1.example.com": { "url": "https://localhost:7054", "caName": "ca-org1", "tlsCACerts": { "pem": "-----BEGIN CERTIFICATE-----\nMIICUTCCAfegAwIBAgIQSiMHm4n9QvhD6wltAHkZPTAKBggqhkjOPQQDA jBzMQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMNU2FuIEZy\nYW5jaXNjbzEZMBcGA1UEChMQb3JnMS5leGF tcGxlLmNvbTEcMBoGA1UEAxMTY2Eu\nb3JnMS5leGFtcGxlLmNvbTAeFw0xOTA5MDQwMjQzMDBaFw0yOTA5MDEwMjQzMDBa\nMHMxCzAJBgNVB AYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1T\nYW4gRnJhbmNpc2NvMRkwFwYDVQQKExBvcmcxLmV4YW1wbGUuY29tMRwwG gYDVQQD\nExNjYS5vcmcxLmV4YW1wbGUuY29tMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE\nz93lOhLJG93uJQgnh93QcPPal5NQXQnAutF KYkun/eMHMe23wNPd0aJhnXdCjWF8\nMRHVAjtPn4NVCJYiTzSAnaNtMGswDgYDVR0PAQH/BAQDAgGmMB0GA1UdJQQWMBQG\nCCsGAQUFBwMCB ggrBgEFBQcDATAPBgNVHRMBAf8EBTADAQH/MCkGA1UdDgQiBCDK\naDhLwl3RBO6eKgHh4lHJovIyDJO3jTNb1ix1W86bFjAKBggqhkjOPQQDA gNIADBF\nAiEA8KTKkjQwb1TduTWWkmsLmKdxrlE6/H7CfsdeGE+onewCIHJ1S0nLhbWYv+G9\nTbAFlNCpqr0AQefaRT3ghdURrlbo\n----- END CERTIFICATE-----\n" }, "httpOptions": { "verify": false } } } }
When fabcar/startFabric.sh executes, we can cross-check that the certificate is propagated correctly.The certificates of peer0.org1 and peer1.org1 are signed by org1's TLS root CA certificate.
Note that all nodes are referenced as localhost, which we will modify later to the public IP address of Fabric Node.
5. User Identity
We have generated a user identity user1 on the Fabric node and saved it in the wallet directory. We can see that there are three corresponding files: the private key, the public key and the certificate object:
We'll copy these files to Rest API Server later.
6. Install Rest API Server node
1. First install npm, node on the Rest API Server node:
sudo apt-get update sudo apt install curl curl -sL https://deb.nodesource.com/setup_8.x | sudo bash - sudo apt install -y nodejs sudo apt-get install build-essentialnode -v npm -v
The validation results are as follows:
2. Then create a directory on the Rest API Server:
mkdir apiserver cd apiserver
3. Next, copy the following file from the Fabric node to the Rest API Server node.We Using loccalhost to copy between two EC2 instances:
# localhost (update your own IP of the two servers) # temp is an empty directory cd temp scp -i ~/Downloads/aws.pem ubuntu@[Fabric-Node-IP]:/home/ubuntu/fabric-samples/first-network/connection-org1.json . scp -i ~/Downloads/aws.pem ubuntu@[Fabric-Node-IP]:/home/ubuntu/fabric-samples/fabcar/javascript/package.json . scp -r -i ~/Downloads/aws.pem ubuntu@[Fabric-Node-IP]:/home/ubuntu/fabric-samples/fabcar/javascript/wallet/user1/ . scp -r -i ~/Downloads/aws.pem * ubuntu@[API-Server-Node-IP]:/home/ubuntu/apiserver/
The results are as follows:
4. You can see that all files have been copied to Rest API Server so far. For consistency, we rename user1/wallet/user1/:
cd apiserver mkdir wallet mv user1 wallet/user1
The results are as follows:
5. Now create the apiserver.js file above on the Rest API Server.
6. Modify the ip address of the fabric node in connection-org1.json connection profile:
sed -i 's/localhost/[Fabric-Node-IP]/g' connection-org1.json
The results are as follows:
7. Add entries in/etc/hosts so that the IP of the fabric s node can be correctly resolved:
127.0.0.1 localhost [Fabric-Node-IP] orderer.example.com [Fabric-Node-IP] peer0.org1.example.com [Fabric-Node-IP] peer1.org1.example.com [Fabric-Node-IP] peer0.org2.example.com [Fabric-Node-IP] peer1.org2.example.com
The results are as follows:
8. Install the necessary dependency packages:
npm install npm install express body-parser --save
9. Everything is ready to start Rest API Server:
node apiserver.js
7. Accessing API
Our API service listens on port 8080. In the following example, we use curl to Demonstrates how to access.
1. Query all vehicle records
curl http://[API-Server-Node-IP]:8080/api/queryallcars
The results are as follows:
2. Add new vehicle records and query
curl -d '{"carid":"CAR12","make":"Honda","model":"Accord","colour":"black","owner":"Tom"}' -H "Content-Type: application/json" -X POST http://[API-Server-Node-IP]:8080/api/addcar curl http://[API-Server-Node-IP]:8080/api/query/CAR12
The results are as follows:
3. Modify the owner of the vehicle and query again
curl http://[API-Server-Node-IP]:8080/api/query/CAR4 curl -d '{"owner":"KC"}' -H "Content-Type: application/json" -X PUT http://[API-Server-Node-IP]:8080/api/changeowner/CAR4 curl http://[API-Server-Node-IP]:8080/api/query/CAR4
The results are as follows:
We can use postman to get the same result:
Original Link: Hyperledger Fabric Rest API Service Development Tutorial - Wizard