Low-Level API JSON

From BlockChainTeleCom wiki
Revision as of 20:38, 31 July 2018 by Opravdin (talk | contribs)
Jump to: navigation, search

API for BT Participants consists of client-server calls and callbacks on specific events.

Supported formats:

* HTTPS POST JSON to Web API
* HTTPS PUT JSON to Web API
* Direct cUrl call to Blockchain_API
* Recommended json style: "snake_case", lower case only


Proactive commands

Create a new Service

"object": "create_service"
"params": {"account_id": 20, "ptservice_id": 196, "memo": "{\"Name\":\"Service_196\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee. It should be unique among all services created by the participant
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests based on the Service. Example: 10, 25, 36
Each Service can contain multiple Offers (Assets).




Update one of existing Services

"object": "update_service"
"params": {"account_id": 20, "ptservice_id": 196, "memo": "{\"Name\":\"Service_196\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee when the Service was created
memo description of the Service as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Service and create Requests based on the Service. Example: 10, 25, 36




Create a new Offer (Asset)

"object": "create_asset"
"params": {"account_id": 20, "ptasset_id": 850, "bcservice_id": 2760, "memo": "{\"Name\":\"Asset_850\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptservice_id int64 ID of the Service assigned by the Offer Assignee when the Service was created. Each Asset should be assigned to a Service
ptasset_id int64 ID of the Asset assigned by the Offer Assignee. It should be unique among all assets created by the participant
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests based on the Service. Example: 10, 25, 36




Update one of existing Offers (Assets)

"object": "update_asset"
"params": {"account_id": 20, "ptasset_id": 350, "memo": "{\"Name\":\"Asset_350\"}", "whitelist_accounts":[25, 30]}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Offer Assignee
ptasset_id int64 ID of the Asset assigned by the Offer Assignee when the Asset was created
memo description of the Asset as json, with multiple tags. Language for description: English
whitelist [optional] list of int64 Blockchain IDs (via comma) of other participants who can read the Asset and create Requests based on the Service. Example: 10, 25, 36




Create a new Request for Bids

"object": "create_bid_request"
"params": {"account_id": 20, "ptrequest_id": 650, "bcasset_ids":[850, 930], "memo": "{\"Name\":\"Request_650\"}", "timeout_sec": 600}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptrequest_id int64 ID of the Request assigned by the Participant. It should be unique among all its requests
bcasset_ids list of int64 IDs of the Assets (via comma) created by other participants
memo description of the Request as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Request, in seconds
Short-term request on one or several assets from one or several service-providers in order to receive bids from them.




Create a new Bid on Request

"object": "create_bid"
"params": {"account_id": 20, "ptbid_id": 720, "bcrequest_id": 7500, "memo": "{\"Name\":\"Bid_720\"}", "timeout_sec": 600}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptbid_id int64 ID of the Bid assigned by the Participant. It should be unique among all its bids
bcrequest_id int64 ID of the Request, the Bid is created to
memo description of the Bid as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Bid, in seconds
Short-term bid on the Request from another service-provider.




Create a new Order on Bid or Asset

"object": "create_order"
"params": {"account_id": 20, "ptorder_id": 1250, "bcasset_id": 850, "bcbid_id": 9850, "amount": 5, "reserved_sum": 12.5, "memo": "{\"Name\":\"Order_1250\"}", "timeout_sec": 600}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptorder_id int64 ID of the Order assigned by the Participant. It should be unique among all its orders
bcbid_id (optional) int64 ID of the Bid, the Order is created on
bcasset_id (optional) int64 ID of the Bid, the Order is created on
amount (optional) int64 amount of the assets, 1 by default
reserved_sum how much SDRt should be reserved for the order
memo description of the Order as json, with multiple tags. Language for description: English
timeout_sec expiration period of the Order, in seconds
Order on a Bid or an Asset (one of them should be specified) for another service-provider.




Accept a received Order

"object": "accept_order"
"params": {"account_id": 20, "bcorder_id": 2450, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
bcorder_id int64 ID of the Order to be accepted
memo description of the Order acceptance as json, with multiple tags. Language for description: English
After acceptance, the reserved sum is blocked on the Request Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.




Report transaction: service is provided for the Order

"object": "accept_order"
"params": {"account_id": 20, "bcorder_id": 2450, "amount": 2, "served_sum": 2.5, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
bcorder_id int64 ID of the Order to be served
amount (optional) int64 amount of the provided assets, 1 by default
served_sum cost of the provided service, in SDRt
memo description of the Report Transaction as json, with multiple tags. Language for description: English
After acceptance, the reserved sum is blocked on the Order Issuer account until "Report" transaction, "Cancel" transaction or the order expiration.



Cancel an own Order

"object": "accept_order"
"params": {"account_id": 20, "ptorder_id": 1250, "memo": "{\"accept_code\":\"Order_2450\"}"}

Response:

200 OK

Requirements:

object name of the API method
account_id unique int64 Blockchain ID of the Participant who creates the Requests
ptorder_id int64 ID of the Order to be cancelled. The ID is assigned be the Order Issuer
memo description of the Order cancellation as json, with multiple tags. Language for description: English
Any order could be cancelled by the Order Issuer.


Billing and Cash Flow

BTBillingDiagram.png

Direct Billing and "Pay-per-Usage" principle provide easy implementation for Participants and fair policy for subscribers. It means that Assignee has guarantee payment for its services, and Issuer pays for consumed services only.

It allows building very flexible packages for subscribers, with combination of mobile services from multiple Operators and of value-added services from multiple Providers. Major cases are described at "Use Cases" section.

Every time a new Request is created, appropriate amount of SDRs is reserved (blocked) on the Issuer's wallet. It provides payment guarantee for the service, so Assignee is able to start servicing the subscriber directly. It's necessary to publish "Report" transaction to notify that the customer was served, otherwise the reserved sum is unblocked after expiration of the validity period and become available for other payments.


How to detect an indecent Participant

There could be some Providers who publish "Report" transaction without servicing the customers. But there is an effective way to detect them in short terms:

  1. Issuer creates a new Request with "faked" User ID. It means that such user is not able to start consuming the service
  2. If Assignee publishes "Report" transaction for this User, it means that indecent Provider has been detected. As a result, such Provider could be fined or even eliminated by voting of "Report" BT members.

So the only way to keep own reputation is to be honest with other Participants. Such method helps building reliable and trusted community.