JDS API

JDS API

The JDS server can provide the data from the SCS blockchain using HTTP requests. The API is separated in to three major groups: Messaging data, Vault data and Trusted Signatures data.

Messaging data

To retrieve messaging data, you have to make the following request to JDS:

<jdsserverhost>:<jdsserverport>/messages?count=<maxcount>

For the simplification of the next command quotes, we will state the server host and port as the one we are running in production now: http://jds.scash.ml:15081
All that will be described further will be valid for any other addresses including your own servers.

The simplest query will look like this:

http://jds.scash.ml:15081/messages?count=1

The server will reply with a valid JSON data like this one:

{ "type": "messages", "count": "1", "filteredOut": "0", "requested": "1", "messages": [
{
"date": "2018-04-30 11:30:47 UTC",
"from": "SRNqTfdk1shGWrzwth84NJLqLnkAj94T5r",
"to": "SYcLh2VBecn7p55kvwaGiBng83puKiidhF SgbJ8iYjE6bUuDn21iDbVuN9KbaK3Co71m ",
"amount": "8.998375SCS",
"trustedSig": "",
"message": "Test of trusted signatures"
}] }

Here are vital parameters explained. The "type" of the messages request is always "messages" or "xxx error". So, you can differentiate the operation success with this field. The "count" parameter tells the count of the "messages" field sub-entries. The "requested" parameter copies your original "count" field of the request. And the "filteredOut" shows the amount of messages that was filtered out by specified conditions; in this request we are not setting filters, so the resulting value is 0.

The "messages" field is an array of message entries. The message entry contains following fields: "date" is the UTC time of when data was published to he blockchain in the format "YYYY-MM-DD hh:mm:ss UTC"; "from" is the SCS address of the message sender; "to" is the list of message receivers separated by the space character; "amount" is the transferred coins amount in the format "xxxSCS"; "trustedSig" is referring to the Trusted Signature of the message sender (if present); and finally, "message" contains the message data itself.

For filtering of messages by the specified criteria, you should use the request in the following format:

http://jds.scash.ml:15081/messages?count=<nnn>&filter1=value1&filter2=value2&...filterN=valueN

The following filtering options are supported:

maxchars=<MaxMessageCharsNumber>

This filters out all messages with a length more than MaxMessageCharsNumber.

minamount=<MinAmountOfSCSTransfer>

This filters out all messages with coins transfers less than MinAmountOfSCSTransfer

maxxsize=<MaxDisplaySizeOfMessagesInHorizontalPixels>

The above filters out all messages with visual representation in dimensions more than MaxDisplaySizeOfMessagesInHorizontalPixels by the X axis.

maxysize=<MaxDisplaySizeOfMessagesInVerticalPixels>

This filters out all messages with visual representation in dimensions more than MaxDisplaySizeOfMessagesInHorizontalPixels by the Y axis.

allowlinks=<0/1>

This parameter allows (1) or disallows (0) the messages containing the html links.

allowimages=<0/1>

This parameter allows (1) or disallows (0) the messages containing the html images.

trustedsigonly=<0/1>

trustedsigonly=1 will filter out all messages not signed with Trusted Signature.

srcaddr=<ScashAddr>

This will filter out any message with a "from" address that is different than the ScashAddr specified.

dstaddr=<ScashAddr>

This parameter will filter out any message with a "to" addresses list that does not contain the specified ScashAddr.

The filters can be combined. For instance, you are running SpeedCash Web Widget displaying the messages on your Web Page. You want to allow it to show only up to 10 messages that are not more than 160 characters in length each, without images and links, from people that send at least 1 SCS to your address SQiXPf38RWwfUZA61AGnB9Mnnekt2Njxzf . The resulting query will be like the following:

http://jds.scash.ml:15081/messages?count=10&maxchars=160&minamount=1&allowlinks=0&allowimages=0&dstaddr=SQiXPf38RWwfUZA61AGnB9Mnnekt2Njxzf

The running of this request will provide the exactly you want. All other messages will be filtered out from the response.

Vault data

The vault data request should start from:

http://jds.scash.ml:15081/vault?count=<maxcount>

The server will reply with valid JSON data response like this one:

{ "type": "vault", "count": "1", "filteredOut": "0", "requested": "1", "documents": [
{
"date": "2018-04-26 14:44:06 UTC",
"hash": "80a335f3288c5d108500348...68930a6897725f7af31bc6",
"from": "SYpb9RsyWWc8CwKhNqhWVEtaUPmLkEVsHq",
"name": "SCS whitepaper.rtf",
"author": "SpeedCash developers",
"version": "Private verison 0.11",
"trustedSig": "",
"comment": "Internal pre-release"
}] }

The header description is the same as for the messages, with exception that result type is "vault" now and the returned data is transferred in "documents" section. It contains the "date" is the UTC time of when the data was published to the blockchain in the format "YYYY-MM-DD hh:mm:ss UTC". "hash" is the public document SHA512 hash. "from" is the address of the transaction sender. "name" is the public document name. "author" is the author name in free format. "version" is the document version in free format. "trustedSig" is the Trusted Signature of  the document author (if present), and "comments" is the public document comment in free format.

Vault data can be filtered in the same manner as the messages one:

http://jds.scash.ml:15081/vault?count=<nnn>&filter1=value1&filter2=value2&...filterN=valueN

The following filtering options are supported:

docauthor=<AuthorName>

This filters out all documents not matching the specified AuthorName (or its prefix).

dochash=<DocumentHashSHA512>

This parameter filters out all documents not matching the specified DocumentHashSHA512 (or its prefix). This is the preferable way to determine whether the specified document is uploaded to Vault or not.

docname=<PublicDocumentName>

The above filters out all documents not matching the specified PublicDocumentName (or its prefix).

docversion=<DocumentVersion>

This filter out all documents not matching the specified DocumentVersion (or its prefix).

trustedsigonly=<0/1>

trustedsigonly=1 will filter out all documents not signed with the Trusted Signature.

If you want to quickly validate if some document was uploaded to SCS blockchain or not, and let's say this document SHA512 hash is  1aa190f76ddc55d8ec9761b0d50a897740fa1c66876a1f7fe930e1f5c3a027220177eb3063d2b4d2e68887d13c2d2a822732306ad92436090a6e590b3b7bb7a6, you have to make the following query:

http://jds.scash.ml:15081/vault?dochash=1aa190f76ddc55d8ec9761b0d50a897740fa1c66876a1f7fe930e1f5c3a027220177eb3063d2b4d2e68887d13c2d2a822732306ad92436090a6e590b3b7bb7a6

The resulting response on the current SCS blockchain clearly states the document was uploaded by the ScashDevelopers on 2018-03-18 07:26:23 UTC, and it is the "Windows Wallet, Build 38, Portable Version".

But for the request with a changed hash (first character of the hash was changed from "1" to "2")

http://jds.scash.ml:15081/vault?dochash=2aa190f76ddc55d8ec9761b0d50a897740fa1c66876a1f7fe930e1f5c3a027220177eb3063d2b4d2e68887d13c2d2a822732306ad92436090a6e590b3b7bb7a6

We have no results:

{ "type": "vault", "count": "0", "filteredOut": "28", "requested": "30", "documents": [] }

That is a valid reply in the case that no resulting data is present.

Read more: Trusted Signatures on SCS blockchain

Leave a Reply

Your email address will not be published. Required fields are marked *