NAV Navbar
javascript

Welcome

Welcome to Blockchain Web Services documentation!

Introduction

Registration

To start using Blockchain Web Services go to bweb.services and sign-up. It’s free.

How It Works

Blockchain Web Services is a set of services made to simplify the use of Smart Contracts without the need to get blockchain accounts (e.g. Ethereum or Cardano) or having to go through hard learning curves.

A smart contract is a computer program or a transaction protocol which is intended to automatically execute, control or document legally relevant events and actions according to the terms of a contract or an agreement.” The Wikipedia.

Once you get your Blockchain Web Services you can start consuming well-documented smart contracts using regular API calls. We use your private Blockchain Web Services keys (never shared with anyone, not even with you) to interact with blockchains like Ethereum or Cardano.

API Endpoint

$.ajax({
    method: 'POST',
    url: 'https://api.bweb.services/v1/call',
   ...
  });

Blockchain Web Services API baseline endpoint is api.bweb.services and current version is v1.

As an example, API operation call will use the following URL:

https://api.bweb.services/v1/call

Authentication

$.ajax({
    ...
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'my-api-key'
    },
    ...
  });

Calling Blockchain Web Services smart contracts requires a personal API Key to authenticate. To get your key, sign in at bweb.services and go to My Account > API Key.


BWS Credits

You must include your Key in all of your API calls as a header attribute:

'X-Api-Key': 'my-api-key'

API Calls Response

API success call response example

{
 "statusCode":200,
 "info":  "{
    \"jobId\":\"543433243\"
  }"
}

API call error response example

{
 "statusCode":404,
 "statusMessage":"incorrect parameters"
}

When calling the API, you can get an HTTP layer transport error, that is, an error that has ocurried before the related API code is executed (e.g. 503, Service Unavailable), or a controlled error, meaning an error that is related to the parameters values you send (e.g. 404, not found - when no data is found for your query). By using this strategy, you will be able to catch and differentiate all kind of API call errors easily.


When no transport layer error is detected, all the API calls will include the next message in the BODY part of the response:

Parameter Type Description
statusCode number The api call result code (e.g. 200 indicates no error).
statusMessage string The status code related message.
info string The requested information.

Error Status Codes

The Blockchain Web Services API uses the following error Status Codes:

Status Code Meaning
400 Bad Request – Check your request parameters.
401 Unauthorized – Check your API key
403 Forbidden / Too Many Requests – Slow down!
404 Not Found – Your API key is valid but there is no related user on our servers.
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested object has been removed
418 I’m a teapot
429 Too Many Requests – Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Main API Methods

API call example.

var parameters = {
  "contractId": "Ethereum.Database.Immutable",
  "parameters": {
    ...
  }
};

$.ajax({
  method: 'POST',
  url: 'https://api.bweb.services/v1/call',
  dataType: 'json',
  data: JSON.stringify(parameters),
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
  },
  ...
  });

API call response example

{
 "statusCode":200,
 "info":  "{
    \"jobId\":\"543433243\"
  }"
}

We mainly use ‘call’ API Method to run a Smart Contract and ‘fetch’ API Method to get Smart Contract results (Smart Contracts execution can take a while).

Smart Contract 'call’ API Method

Use https://api.bweb.services/v1/call to run Blockchain Web Services Smart Contracts passing the following parameters:

Parameter Type Value(s) Description
contract string check Smart Contracts The contract id.
version number 1,2,3,… The contract version to use.
network string ropsten, ethereum The network id to save data to.
operation string check Smart Contracts The operation id to call.
parameters json check Smart Contracts The operation required parameters.

Please note:

‘call’ API Response

API call response includes the ‘jobId’ to use to get Smart Contract results.

{ "jobId": "aacee908-3a85-4966-945c-ab8f09ebabf9" }

Check the response object you get when calling Blockchain Web Services API.

Smart Contract ‘fetch’ API Method

API call example.

var parameters = {
  "jobId": "b064cc6b-f394-4ca4-9c51-be506e4cc59d",
};

$.ajax({
  method: 'POST',
  url: 'https://api.bweb.services/v1/fetch',
  dataType: 'json',
  data: JSON.stringify(parameters),
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
  },
  ...
  });

Fetch API call response example

{
    "statusCode": 200,
    "statusMessage": "",
    "info": {
        "Status":{ "Value":"registered"},
        "TimestampInMillis":1674504952,
        "Request": {
            "contract": "Ethereum.Database.Immutable ",
            "version": 1,
            "network": "ropsten",
            "operation": "insertBytes32",
            "parameters": {
                "key": "a-key",
                "value": "Hello World!"
            },
            "Guid":"b064cc6b-f394-4ca4-9c51-be506e4cc59d"
        }
}

Use https://api.bweb.services/v1/fetch to get a previously started Smart Contract call, indicating the jobId you get when running ‘call’ API Method:

Parameter Type Value(s)
jobId string The jobId you get when running a Smart Contract

‘fetch’ API Response

The fetch API method will return the status of your Smart Contract call as part of the info parameter:

Parameter Description
Status The current status of Smart Contract execution
TimestampInMillis The status timestamp in milliseconds
Request The original request you did to call the Smart Contract
Result When Status is ‘finished’ the smart contract results

Required Funds

Blockchain Web Services is free, but calling Smart Contracts requires funds: “It is the fuel that allows it to operate” (you can check how Gas and Fuel works for Ethereum here).

To get your account funded go to My Account > Credits and complete your credits purchase.


BWS Credits

Remember Blockchain Web Services is free and funds are spent when calling smart contracts.

Smart Contracts

Ethereum.Database.Immutable

This contract is used for immutable Ethereum database operations.

An immutable object is an object whose state cannot be modified after it is created

Contract Address

You can check Blockchain Web Services contract at the following addresses (to verify click on the contract address link).

Network Id Contract Address
ethereum
ropsten 0x2dB6Bbb6ff06D1fdC3c04705E1284dF99981D205

Operations

Use the following operations to save (and get) data to Ethereum blockchain distributed ledger database.

:: insertBytes32

var parameters = {
    "contract": "Ethereum.Database.Immutable",
    "version": 1,
    "network": "ropsten",
    "operation": "insertBytes32",
    "parameters": {
      "key": "a-key",
      "value": "Hello World!"
    }
}

$.ajax({
    method: 'POST',
    url: 'https://api.bweb.services/v1/call',
    data: JSON.stringify(parameters),
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
    },
    dataType: 'json',
    success: function (response) {
      console.log(response); 
    },
    error: function (xhr, textStatus, errorThrown) {
      console.log(xhr);
    }
  });

If successfull, the call will return the related Job Id to fetch for results.

Saves up to 32 characters string value in Ethereum database.

Request Parameters

Use the following parameters to call insertBytes32 operation:

Parameter Value
contract Ethereum.Database.Immutable
operation insertBytes32
parameters insertBytes32 Operation Parameters

Check Passing Parameters for other required parameters.

insertBytes32 Operation Parameters

The following operation parameters can be used to save a string you can later query by using the keyvalue.

Parameter Type Value(s) Description
key string 32 characters string The key for data to save.
value string 32 characters string The value to save on database.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).

:: selectBytes32

var parameters = {
    "contract": "Ethereum.Database.Immutable",
    "version": 1,
    "network": "ropsten",
    "operation": "selectBytes32",
    "parameters": {
      "key": "a-key"
    }
}

$.ajax({
    method: 'POST',
    url: 'https://api.bweb.services/v1/call',
    data: JSON.stringify(parameters),
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
    },
    dataType: 'json',
    success: function (response) {
      console.log(response); 
    },
    error: function (xhr, textStatus, errorThrown) {
      console.log(xhr);
    }
  });

If successfull, the call will return the related Job Id to fetch for results.

Gets a value you previously stored on Ethereum database by calling insertBytes32.

Request Parameters

Use the following parameters to call selectBytes32 operation:

Parameter Value
contract Ethereum.Database.Immutable
operation selectBytes32
parameters selectBytes32 Operation Parameters

Check Passing Parameters for other required parameters.

selectBytes32 Operation Parameters

Set the key value to get the data you previously saved.

Parameter Type Value(s) Description
key string 32 characters string The key for data to save.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).