Questions

What does a 401 response code mean?

Quite simply, if you get a 401 response, it probably means your authorization token has expired. The token will automatically expire after 12 hours. You can get a new authorization token for your ‘write’ tasks as often as you like, but for more efficient use of the Logware API, we recommend you cache your token for 12 hours. If you get a 401 response, simple request a new token and initiate your request again.

If you are interested in the design of this API, it closely follows the pattern found here.

Getting started with the Logware API?

Before you start coding in your respective language, be sure to understand the steps to work with Logware. The logic flow when working with the Logware API has three basic steps. The steps are the same for committing your payload to Logware, regardless of it being a ‘hash’ value or ‘data’ value.

To get your free API key for testing, please contact service@logware.io.

First, you will authenticate with the API. You only need to do this for writing your payload to Logware. Reading from Logware does not require authentication, but it is throttled to prevent abuse.

Second, to write your payload to Logware, you would:

  1. Write the payload to the chain, get back a temporary Task Id.
  2. Using your temporary Task Id, read the chain and get back a permanent Transaction Id.
  3. Store your Transaction Id, you will need it in the future. It is your receipt and marker. Do not store or reuse the Task Id.

Third, in the future, you might want to read your payload from the chain. To do so, you need to the Transaction Id:

  1. Using your permanent Transaction Id, ask for a temporary Task Id.
  2. Using your temporary TaskId, read the chain to get the payload you are looking for.

Each action is a pair of POST/GET events. POST your request, get back a temporary Task Id. Then use the Task Id to GET the resulting Transaction Id or payload.

Sample BASH script of reading and writing data to the Lynx blockchain via the Logware API

The following code can be copy/pasted into a .sh file on your Linux command line. You must update the apiUsername and apiPassword with your own credentials (which you can get here). Be sure to make the file executable.

#!/bin/bash
#
echo "Logware - Demo of reading and writing data to the Lynx blockchain via the Logware API with Linux BASH scripting."
#
# In order to access the API, please contact the Logware team
# at https://logware.io/#contact
#
apiUsername="{Update me with a Username}"
apiPassword="{Update me with a Password}"
#
# By default, use of the test environment is free. Understand that at any time
# the environment can be destroyed and all data will be lost.
#
apiEnvironment="test"
#apiEnvironment="prod"
#
# Support for passing a param via CLI to the script. A default value is set too.
#
content="$1"
[ -z "$1" ] && content="https://www.npr.org/2019/07/23/744582053/senate-approves-bill-to-prevent-sept-11-victims-fund-from-running-out-of-money"
echo "Content being written: '${content}'"
#
# Write section goes to https://api.logware.io/ and requires AUTH.
# Log in and get token
#
TOKEN=$(curl -s -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"login":"'"$apiUsername"'","password":"'"$apiPassword"'"}' https://api.logware.io/api/users/authenticate | jq -r '.token')
echo "Logged in as '$apiUsername'"
#
# Now that we have the AUTH token, let's send the write request.
#
WRITE=$(curl -s -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --data '{"env":"'"$apiEnvironment"'","data":"'"$content"'"}' https://api.logware.io/api/data)
WRITE="${WRITE%\"}" && WRITE="${WRITE#\"}" # Strip quotes from body
echo "WRITE Logware TaskId is '$WRITE'"
echo "Waiting for write to complete..."
#
# Sometimes a delay occurs, so let's wait for write. Now that was have the
# TaskId, we can query for the Lynx Transaction Id for future reference -
# both via Logware or offline directly with Lynx.
#
TXID="null"
while [ "$TXID" = "null" ] ; do
	# Get the results of the write request
	TXID=$(curl -s -H 'Accept: application/json' -H "Authorization: Bearer $TOKEN" https://api.logware.io/api/data/$apiEnvironment/${WRITE} | jq -r '.Content[0]')
	echo "Lynx Transaction Id is '$TXID'"
	sleep 5
done
#
# Read section goes to https://api.logware.io/ and is anonymous. Notice the URL
# is different from the API endpoint for WRITE.
#
READ=$(curl -s -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"env": "'"$apiEnvironment"'", "txid": "'"$TXID"'"}' https://api.logware.io/api/data/retrieve)
echo "READ TaskId is '$READ'"
echo "Waiting for read..."
#
# Due to an occasional delay, let's query until we get a response for the
# original data with this READ request.
#
DATA="null"
while [ "$DATA" = "null" ] ; do
	# Get the results of the read request
	DATA=$(curl -s -H 'Accept: application/json' https://api.logware.io/api/data/retrieve/$apiEnvironment/${READ} | jq -r '.Content[0]')
	echo "DATA returned is '$DATA'"
	sleep 5
done
#

What is Logware?

Logware is a ‘blockchain as a service’ that allows customers to permanently store cryptographic hashes of sensitive data quickly. It’s a high volume, low cost service that creates transparency for the businesses that use it – and trust for the customers it impacts.

Logware enables businesses to quickly store metadata in bulk on a low-cost, eco-friendly blockchain.

How secure is Logware at storing my data?

Since Logware only stores metadata, to be clear – cryptographic hashes – your data is a secure as you keep it. Logware does not store your actual raw data, only the checksum of that data. The metadata is stored on a public blockchain that anyone an access ad verify, but the ownership of the checksum and related raw data is not attached. An analogy would be like hiding data in plain site for all to see, but the data has no value to anyone but its owner. Once metadata is written to the public blockchain, it can’t be changed or manipulated.

How long is my data accessible after storing it on Logware?

Once data is written to the blockchain via the Logware API, it becomes permanent. It can’t be changed nor can it be forgotten or removed. This is important. This is the reason that only cryptographic hashes are stored. The original data is not stored, only the hash. If the original data is deleted or becomes non-relevant, then the metadata loses its purpose, but it remains on the historical blockchain for as long as the blockchain exists.

Which blockchain platform does Logware store its data?

Logware is a commercial application built on top of the open source Lynx Project. The development team that maintains the Lynx Project is the same development team that created and maintains the Logware project. The positive benefit of this arrangement is to ensure that no change occurs to the Lynx Project that might negatively impact the Logware Blockchain As A Service platform. While Lynx is a public, open source project, the Logware team controls the change management so it always falls in line with the interests of Logware and it’s customers.

Lynx Project Logo

The second reason that the Lynx Project is used is due to it’s eco-friendly, low costs infrastructure. The Lynx Blockchain has a very small energy requirement to sustain itself. It is a natural choice for a Blockchain As A Service business due to it’s long term sustainable design and low volatility public coin price.

What is a cryptographic hash?

A cryptographic hash function is an algorithm that can be run on data such as an individual file or a password to produce a value called a checksum. The main use of a cryptographic hash function is to verify the authenticity of a piece of data. Two files can be assumed to be identical only if the checksums generated from each file, using the same cryptographic hash function, are identical.

https://www.lifewire.com/cryptographic-hash-function-2625832

This quote from the lifewire article describes it quite well. We recommend you read the article in full to fully understand the use cases of cryptographic hashes and why a system like Logware that can store them in bulk on a blockchain has value.

What if my company uses Logware, and Logware goes out of business? Do I lose access to my hash data?

No, you don’t lose access. All hash data that Logware stores is publicly accessible via the Lynx blockchain. If Logware goes out of business, your development team could build tools to access the public blockchain, and your respective data. As long as at least 2 Lynx nodes are still operating in the world at any one time, your data is intact and you can access it. It’s very hard to completely kill off a public blockchain.

How much data can my business store with Logware?

Logware has no limit to the amount of cryptographic hash data it can store. A blockchain is like a ledger book with an unlimited number of blank pages. Sure, it might get heavy after a while, but hard drive space is cheap and gets cheaper every year. The issue comes down to speed. The Logware API is capable of queueing a backlog, so a burst of requests can be received and stored, but it might take a few seconds to complete the task. This nice thing about the API is this work is all handled automatically for the customer. The API can even provide a Logware Identification Number that identifies the transaction before the hash is even stored. It’s unlikely a record will be needed within seconds of submitting it so it works well for almost all use cases.