Skip to content

API Reference

Jump to bottom
Colin Lowenberg edited this page Sep 6, 2018 · 86 revisions

The Disgo API is a modern HTTP interface that follows the REST architecture (https://en.wikipedia.org/wiki/Representational_state_transfer) with a JSON format. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

HTTP Responses

Disgo uses conventional HTTP response codes to indicate the success or failure of an API request. Response codes in the 200-299 range indicate success, codes in the 400-499 range indicate an error that failed given the information provided, and codes in the 500-599 range indicate an error with the Dispatch node. When a request is valid but does not complete successfully, we return a 402 error code.

Status and Error Codes

Status Code. Summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
409 - Conflict The request conflicts with another request
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Disgo's end. (These are rare.)

Example API Requests

Please use the base URL http://seed.dispatchlabs.io:1975/ for all API requests.

Request Description
RequestDelegates Get Delegates
RequestAccounts Get Accounts
RequestAccounts Get Account Details
RequestGetTransactions List all transactions
RequestGetTransactionsByAddress List all transactions from an address
RequestGetTransactionsByAddress List all transactions to an address
RequestGetStatus Get Transaction Status
RequestNewTransaction Send a New Transaction

List Delegates

This API call will return a list of all delegates on the Dispatch network.

Example request

curl 'http://seed.dispatchlabs.io:1975/v1/delegates'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "address": "fbaadf32f8fc1d33eed36e4125d4926b65cf6085",
            "grpcEndpoint": {
                "host": "35.203.147.207",
                "port": 1973
            },
            "httpEndpoint": {
                "host": "35.203.147.207",
                "port": 1975
            },
            "type": "Delegate"
        },
    ..... ],
    "created": "2018-09-05T22:30:28.845499275Z"
}

List Accounts

This endpoint returns a list of all accounts on the Dispatch network.

Example request

curl 'http://35.185.224.243:1975/v1/accounts'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "address": "276856c5a7b46e2ad8652da146127cc6e1b183c1",
            "name": "Colin-Lowenberg",
            "balance": 1000,
            "updated": "2018-08-29T18:49:17.32249325Z",
            "created": "2018-08-29T18:48:29.648461696Z",
            "nonce": 0
        },...{}],
    "created": "2018-09-05T23:51:03.907947185Z"
}

Get Account details

This endpoint retrieves the detailed account information and balance of an address.

Example request

curl 'http://35.185.224.243:1975/v1/accounts/2674ad19f8472a953b4b9eebf53e9fce4e9bf718'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": {
        "address": "2674ad19f8472a953b4b9eebf53e9fce4e9bf718",
        "name": "",
        "balance": 0,
        "transactionHash": "c0f53ec38a6dc04a632d45aa570cb77903ef1d302f547e4583bb7313400fda1a",
        "updated": "2018-08-28T21:20:41.192534758Z",
        "created": "2018-08-28T21:20:29.358826557Z",
        "nonce": 0
    },
    "created": "2018-09-05T23:57:13.958756313Z"
}

Transactions

This is an object representing your Disgo transfer of tokens, deployment of smart contract, and smart contract execution. These are 3 types of transactions, respectively 0, 1, and 2.

The transaction object

Attribute Type Description Optional Example
hash string SHA3 hash of the object NO "603378477301a29..."
type number The type of the transaction NO 0
from string Address of from where the tokens came from NO "7777f2b40aa..."
to string Address of where to transfer the tokens YES "c296220327589..."
value number Number of tokens to transfer YES 999
code string Smart contract deployment code YES "608060405234..."
abi string Smart contract guide YES "5b7b0a202..."
method string Name of Method being called YES "getVar5"
params JSON array Parameters for Method YES ["5555"] , or []
time string Time of the transfer formatted in ISO 1806 NO 1528923572369
Signature string Hash owner's signature NO "7b60acd9e8f972..."
hertz number Amount of bandwidth to use YES 0
fromName string From account nickname YES ""
toName string To account nickname YES ""

Get all transactions

Call to retrieve all transactions on a Dispatch delegate.

Example request

curl 'http://35.185.224.243:1975/v1/transactions/'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "hash": "014ac414be6cff6db9d20e131418dae502a4e7d6efaa015b73cb8c2c05031f3b",
            "type": 0,
            "from": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "to": "9fdd1b96f5eda025ba2ff9f8201cb496af839d0f",
            "value": 5,
            "abi": "{}",
            "time": 1535527996533,
            "signature": "2190831ad6e28c9e664c03905ba9e82c1b208de14bfea9367ed3addc95ac03985a278d43ffd6bd33e28fd9d910116d6a7ea4e65efd781d787a53cfb94c9485e501",
            "hertz": 0,
            "receipt": {
                "transactionHash": "",
                "status": "",
                "created": "0001-01-01T00:00:00Z"
            }
        },.... {}
    ],
    "created": "2018-09-06T00:03:18.822716546Z"
}

Retrieving all transactions sent from an address.

Call to retrieve all transactions filtered using from parameter (or to).

Example request

curl 'http://35.185.224.243:1975/v1/transactions/from/6b728eb24434d31a3e7153f64da0a039bff307e4'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "hash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
            "type": 2,
            "from": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "to": "1a08733f2a9ebf6b33ea792f10a153364c406ff1",
            "abi": "5b7b22636f6e7374616e74223a747275652c22696e70757473223a5b7b226e616d65223a2279222c2274797065223a2275696e74323536227d5d2c226e616d65223a22706c75734f6e65222c226f757470757473223a5b7b226e616d65223a2278222c2274797065223a2275696e74323536227d5d2c2270617961626c65223a66616c73652c2273746174654d75746162696c697479223a2270757265222c2274797065223a2266756e6374696f6e227d5d",
            "method": "plusOne",
            "params": [
                1
            ],
            "time": 1535528027657,
            "signature": "25ac7d5afc36ef329d70a03feff833897f1ded26a3d10a888934dfcc76f5975e30b44d5f19722812831ea6d6c90fb0d0336a502a8b8c7d0a6adfac0e5e07b18100",
            "hertz": 2,
            "receipt": {
                "transactionHash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
                "status": "Ok",
                "contractAddress": "1a08733f2a9ebf6b33ea792f10a153364c406ff1",
                "contractResult": [
                    2
                ],
                "created": "2018-08-29T07:33:52.918897036Z"
            },
            "gossip": [
                {
                    "hash": "5969084427bf52920f57ca7302e1cf92282ce5e1d3c52edd7181fb5c42669f99",
                    "address": "dea18bfabd1ebb0e2249652031a0f7c12c5f09ed",
                    "transactionHash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
                    "time": 1535528027905,
                    "signature": "3e89fd88b53b0303e05f8b922dad9a5e9b7e759c60ef513079ab50d0883b620657f4e14d00a3df2854d68dc473ee8d1f0c4b8047eec2725f95c480c53468009501"
                },...
            ]
        },...
     ],
    "created": "2018-09-06T00:11:12.44461441Z"
}

Check the status of a transaction

To check on the status of your transaction, ask a delegate with the id of the receipt that you received.

Example request

curl 'http://35.185.218.82:1975/v1/receipt/{hash}'

Example response

{"id":"480fd9bc-4962-4e98-825e-387e5ea83c14","type":"NewTransaction","status":"Pending","created":"2018-06-26T21:22:46.229254106Z"}

Create a new transaction

Note that any parameter that says optional you should include, but leave as either an empty string or 0; with the exception of params which should be an if empty.

Example request

curl -X POST -d '{"hash":"419fdf66583316a14fb98a60888a0e70972dc0437f8e9c18b355495b00e73507","type":0,"from":"3ed25f42484d517cdfc72cafb7ebc9e8baa52c2c","to":"d70613f93152c84050e7826c4e2b0cc02c1c3b99","value":999,"code":"","abi":"","method":"","params":null,"time":1528409587556,"signature":"4264dea5973016e917a3aa0d92865b63b8e6404d50fb864717430acfc718c58704e1e146c0e5fcdce02ff98e96303b2a84375bf1de68ce9c452cd4454d87d1e800","hertz":0,"fromName":"","toName":""}' 'http://seed.dispatchlabs.io/v1/transactions'

Example response

{
	{"id":"480fd9bc-4962-4e98-825e-387e5ea83c14","type":"NewTransaction","status":"Pending","created":"2018-06-26T21:22:46.229254106Z"}
}

Clone this wiki locally