Skip to content

Latest commit

 

History

History
774 lines (714 loc) · 22 KB

OstJsonApi.md

File metadata and controls

774 lines (714 loc) · 22 KB
Raw

OST JSON APIs

OST JSON APIs are a set of asynchronous methods that make API calls to OST Platform servers.

Table of Contents

Before We Begin

  • Although it is NOT RECOMMENDED, but if your app needs to allow multiple users to login on same device, the app must:
    • ensure to pass the userId of the currently logged-in and authenticated user.
    • ensure that the user has not logged-out before processing/displaying the response.
  • App must initialize the SDK before initiating any JSON API.
  • App must perform setupDevice workflow before initiating any JSON API.
  • All OstJsonApi methods expect userId as first parameter because all requests need to be signed by the user's API key.
  • It's always good to check if the device can make API calls by calling OstWalletSdk.getCurrentDeviceForUserId method.
    • Any device with status REGISTERED, AUTHORIZING, AUTHORIZED, RECOVERING or REVOKING can make this API call.

JSON API Types

The JSON APIs can be categorized into 2 groups.

  • Entity API - The APIs that get entities (e.g. current-device, price-point, balance, etc.)
  • List API - The APIs that get list of entities and support pagination (e.g. device list, transactions)

Importing OstJsonApi

Use the following code to import OstJsonApi

import {OstJsonApi} from '@ostdotcom/ost-wallet-sdk-react-native';

Entity API

Get Current Device

API to get user's current device.

While the equivalent getter method OstWalletSdk.getCurrentDeviceForUserId gives the data stored in SDK's database, this method makes an API call to OST Platform.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";

/**
   * API to get user's current device.
   * @param {String} userId - Ost User id
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getCurrentDeviceForUserId(
    userId,  
    (data) => {
      console.log(data);
    },
    (error, response) => {} 
)

Sample Response
{
  "device": {
    "updated_timestamp": 1566832473,
    "status": "AUTHORIZED",
    "api_signer_address": "0x674d0fc0d044f085a87ed742ea778b55e298b429",
    "linked_address": "0x0000000000000000000000000000000000000001",
    "address": "0x8d92cf567191f07e5c1b487ef422ff684ddf5dd3",
    "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
  },
  "result_type": "device"
}

Get Balance

API to get user's balance.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";

/**
   * Api to get user balance
   * @param {String} userId - Ost User id
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getBalanceForUserId(
    userId,  
    (data) => {
      console.log(data);
    },
    (error, response) => {} 
)

Sample Response
{
  "balance": {
    "updated_timestamp": 1566832497,
    "unsettled_debit": "0",
    "available_balance": "10000000",
    "total_balance": "10000000",
    "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
  },
  "result_type": "balance"
}

Get Price Points

API to get price-points of token's staking currency (OST or USDC).

This API call is generally needed to compute the current fiat value to your brand-tokens. E.g. displaying user's balance in fiat.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";

/**
   * Api to get user balance
   * @param {String} userId - Ost User id
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getPricePointForUserId(
    userId,  
    (data) => {
      console.log(data);
    },
    (error, response) => {} 
)

Sample Response
{
  "price_point": {
    "USDC": {
      "updated_timestamp": 1566834913,
      "decimals": 18,
      "GBP": 0.8201717727,
      "EUR": 0.9028162679,
      "USD": 1.0025110673
    }
  },
  "result_type": "price_point"
}

Get Balance And Price Points

This is a convenience method that makes OstJsonApi.getBalanceForUserId and OstJsonApi.getPricePointForUserId API calls and merges the response.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";

/**
   * Api to get user balance
   * @param {String} userId - Ost User id
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getBalanceWithPricePointForUserId(
    userId,  
    (data) => {
      console.log(data);
    },
    (error, response) => {} 
)

Sample Response
{
  "balance": {
    "updated_timestamp": 1566832497,
    "unsettled_debit": "0",
    "available_balance": "10000000",
    "total_balance": "10000000",
    "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
  },
  "price_point": {
    "USDC": {
      "updated_timestamp": 1566834913,
      "decimals": 18,
      "GBP": 0.8201717727,
      "EUR": 0.9028162679,
      "USD": 1.0025110673
    }
  },
  "result_type": "balance"
}

Get Pending Recovery

API to get user's pending recovery. A pending recovery is created when the user recovers the device using their PIN.

This API will respond with UNPROCESSABLE_ENTITY API error code when user does not have any recovery in progress.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";

/**
   * Api to get user balance
   * @param {String} userId - Ost User id
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */
OstJsonApi.getPendingRecoveryForUserId(
    userId,  
    (data) => {
      console.log(data);
    },
    (error, response) => {
      console.log( error );
      if ( error.is_api_error ) {
        if ( "UNPROCESSABLE_ENTITY" === String(error.api_error.code).toUppercase() ) {
          console.log("User does not have any recovery in progress.");
          // You can safely ignore this error.
          return;
        }
      }
    } 
)

Sample Response
 {
  "devices": [
    {
      "updated_timestamp": 1566902100,
      "status": "REVOKING",
      "api_signer_address": "0x903ad1a1017c14b8e6b0bb1dd32d3f65a8741732",
      "linked_address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa",
      "address": "0x629e13063a2aa24e2fb2a49697ef871806071550",
      "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
    },
    {
      "updated_timestamp": 1566902100,
      "status": "RECOVERING",
      "api_signer_address": "0x6f5b1b8df95cbc3bd8d18d6c378cef7c34644729",
      "linked_address": "null",
      "address": "0x33e736a4761bc07ed54b1ceb82e44dfb497f478c",
      "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
    }
  ],
  "result_type": "devices"
}

Sample Error

The getPendingRecoveryForUserId API will respond with UNPROCESSABLE_ENTITY API error code when user does not have any recovery in progress.

{
  "api_error": {
    "internal_id": "***********",
    "error_data": [],
    "msg": "Initiate Recovery request for user not found.",
    "code": "UNPROCESSABLE_ENTITY"
  },
  "is_api_error": 1,
  "error_message": "OST Platform Api returned error.",
  "internal_error_code": "***********",
  "error_code": "API_RESPONSE_ERROR"
}

Get Redeemable Sku Details

API to get redeemable sku details.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";
let skuDetailId = "2";
let extraParams = {};

/**
   * Api to get redeemable skus
   * @param {String} userId - Ost User id
   * @param {String} skuDetailId - Sku detail id got from list of Redeemable skus
   * @param {Object} extraParams (@nullable).
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */


OstJsonApi.getRedeemableSkuDetails(userId, skuDetailId ,extraParams, (response) => {
    console.log(response);    
  }, (error)=> {
    console.log("An error has occurred while fetching redeemable sku details.");
    console.log( error );
  });

Sample Response
{
   "result_type":"redemption_product",
   "redemption_product":{
      "status":"active",
      "images":{
         "detail":{
            "original":{
               "size":90821,
               "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-d-original.png",
               "width":150,
               "height":150
            }
         },
         "cover":{
            "original":{
               "size":193141,
               "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-c-original.png",
               "width":320,
               "height":320
            }
         }
      },
      "availability":[
         {
            "country_iso_code":"USA",
            "country":"USA",
            "currency_iso_code":"USD",
            "denominations":[
               {
                  "amount_in_wei":"49938358",
                  "amount_in_fiat":5
               },
               {
                  "amount_in_wei":"99876717",
                  "amount_in_fiat":10
               },
               ...
            ]
         },
         {
            "country_iso_code":"CAN",
            "country":"Canada",
            "currency_iso_code":"CAD",
            "denominations":[
               {
                  "amount_in_wei":"37547638",
                  "amount_in_fiat":5
               },
               {
                  "amount_in_wei":"75095276",
                  "amount_in_fiat":10
               },
               ...
            ]
         },
         {
            "country_iso_code":"GBR",
            "country":"United Kingdom",
            "currency_iso_code":"GBP",
            "denominations":[
               {
                  "amount_in_wei":"64855011",
                  "amount_in_fiat":5
               },
               {
                  "amount_in_wei":"129710022",
                  "amount_in_fiat":10
               },
               ...
            ]
         },
         {
            "country_iso_code":"IND",
            "country":"India",
            "currency_iso_code":"INR",
            "denominations":[
               {
                  "amount_in_wei":"1396",
                  "amount_in_fiat":0.01
               },
               {
                  "amount_in_wei":"139609",
                  "amount_in_fiat":1
               },
               ...
            ]
         }
      ],
      "id":"2",
      "updated_timestamp":1582024811,
      "description":{
         "text":null
      },
      "name":"Starbucks"
   }
}

List API

All List APIs support pagination. The response of all List APIs has an extra attribute meta. To determine if next page is available, the app should look at meta.next_page_payload. If meta.next_page_payload is an empty object ({}), next page is not available.

Get Transactions

API to get user's transactions.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";
let nextPagePayload = null;

/**
   * Api to get user's transactions
   * @param {String} userId - Ost User id
   * @param {Object} nextPagePayload (@nullable). Pass null to get first page.
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getTransactionsForUserId(userId, nextPagePayload, 
  (response) => { 
    console.log(response);
    // Let's check if more pages of data is available.
    if ( response.meta ) {
      let nextPagePayloadFromResponse = response.meta.next_page_payload || {};
      if ( Object.keys(nextPagePayloadFromResponse).length > 0 ) {
        // Next page is available.
        // Update nextPagePayload 
        nextPagePayload = nextPagePayloadFromResponse;
        // To fetch the next page, pass the updated nextPagePayload.
      }
    }
  },
  (error) => { 
    console.log("An error has occurred while fetching transactions.");
    console.log( error );
  });

Sample Response

Please refer to the Transactions Object for a detailed description.

{
  "meta": {
    "total_no": 14,
    "next_page_payload": {
      "pagination_identifier": "*****************************************************"
    }
  },
  "transactions": [
    {
      "meta_property": {
        "details": "Awesome Post",
        "type": "user_to_user",
        "name": "Like"
      },
      "rule_name": "Direct Transfer",
      "block_timestamp": 1566843589,
      "block_confirmation": 969,
      "transaction_fee": "94234000000000",
      "gas_price": "1000000000",
      "nonce": 613,
      "from": "0x6ecbfdb2ebac8669c85d61dd028e698fd6403589",
      "id": "4efa1b45-8890-4978-a5f4-8f9368044852",
      "transfers": [
        {
          "kind": "transfer",
          "amount": "200000",
          "to_user_id": "a87fdd7f-4ce5-40e2-917c-d80a8828ba62",
          "to": "0xb29d32936280e8f05a5954bf9a60b941864a3442",
          "from_user_id": "71c59448-ff77-484c-99d8-abea8a419836",
          "from": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9"
        }
      ],
      "block_number": 3581559,
      "updated_timestamp": 1566843589,
      "status": "SUCCESS",
      "gas_used": 94234,
      "value": "0",
      "to": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9",
      "transaction_hash": "0xee8033f9ea7e9bf2d74435f0b6cc172d9378670e513a2b07cd855ef7e41dd2ad"
    },
    {
      "meta_property": {
        "details": "Nice Pic",
        "type": "user_to_user",
        "name": "Fave"
      },
      "rule_name": "Direct Transfer",
      "block_timestamp": 1566843547,
      "block_confirmation": 983,
      "transaction_fee": "109170000000000",
      "gas_price": "1000000000",
      "nonce": 612,
      "from": "0x6ecbfdb2ebac8669c85d61dd028e698fd6403589",
      "id": "7980ee91-7cf1-449c-bbaf-5074c2ba6b29",
      "transfers": [
        {
          "kind": "transfer",
          "amount": "1600000",
          "to_user_id": "a87fdd7f-4ce5-40e2-917c-d80a8828ba62",
          "to": "0xb29d32936280e8f05a5954bf9a60b941864a3442",
          "from_user_id": "71c59448-ff77-484c-99d8-abea8a419836",
          "from": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9"
        }
      ],
      "block_number": 3581545,
      "updated_timestamp": 1566843549,
      "status": "SUCCESS",
      "gas_used": 109170,
      "value": "0",
      "to": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9",
      "transaction_hash": "0x3e3bb3e25ab3a5123d1eaf20e1c31ab88bd56500c5cdfd2e32025c4df32735b3"
    },
    ...
    ...
  ],
  "result_type": "transactions"
}

Get Devices

API to get user's devices.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";
let nextPagePayload = null;

/**
   * Api to get user's device
   * @param {String} userId - Ost User id
   * @param {Object} nextPagePayload (@nullable). Pass null to get first page.
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */

OstJsonApi.getDeviceListForUserId(userId, nextPagePayload, 
  (response) => { 
    console.log(response);
    // Let's check if more pages of data is available.
    if ( response.meta ) {
      let nextPagePayloadFromResponse = response.meta.next_page_payload || {};
      if ( Object.keys(nextPagePayloadFromResponse).length > 0 ) {
        // Next page is available.
        // Update nextPagePayload 
        nextPagePayload = nextPagePayloadFromResponse;
        // To fetch the next page, pass the updated nextPagePayload.
      }
    }
  },
  (error) => { 
    console.log("An error has occurred while fetching devices.");
    console.log( error );
  });

Sample Response
{
  "meta": {
    "next_page_payload": {}
  },
  "devices": [
    {
      "updated_timestamp": 1566832473,
      "status": "AUTHORIZED",
      "api_signer_address": "0x674d0fc0d044f085a87ed742ea778b55e298b429",
      "linked_address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa",
      "address": "0x8d92cf567191f07e5c1b487ef422ff684ddf5dd3",
      "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
    },
    {
      "updated_timestamp": 1566839512,
      "status": "AUTHORIZED",
      "api_signer_address": "0x2e12c4f6a27f7bdf8e58e628ec29bb4ce49c315e",
      "linked_address": "0x0000000000000000000000000000000000000001",
      "address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa",
      "user_id": "71c59448-ff77-484c-99d8-abea8a419836"
    }
  ],
  "result_type": "devices"
}

Get Redeemable Skus

API to get redeemable skus.

Usage
/*
  Please update userId as per your needs. 
  Since this userId does not belong to your economy, you will get an error if you do not change it.
*/
let userId = "71c59448-ff77-484c-99d8-abea8a419836";
let nextPagePayload = null;

/**
   * Api to get redeemable skus
   * @param {String} userId - Ost User id
   * @param {Object} nextPagePayload (@nullable). Pass null to get first page.
   * @param {function} Success callback with success data
   * @param {function} Failure callback with error and failure response
   * @public
 */


OstJsonApi.getRedeemableSkus(userId, nextPagePayload , (respones) => {
    console.log(response);
    // Let's check if more pages of data is available.
    if ( response.meta ) {
      let nextPagePayloadFromResponse = response.meta.next_page_payload || {};
      if ( Object.keys(nextPagePayloadFromResponse).length > 0 ) {
        // Next page is available.
        // Update nextPagePayload 
        nextPagePayload = nextPagePayloadFromResponse;
        // To fetch the next page, pass the updated nextPagePayload.
      }
    }
  }, (error)=> {
    console.log("An error has occurred while fetching redeemable skus.");
    console.log( error );
  });

Sample Response
{
   "meta":{
      "next_page_payload":{
      }
   },
   "result_type":"redemption_products",
   "redemption_products":[
      {
         "status":"active",
         "updated_timestamp":1582024811,
         "id":"2",
         "description":{
            "text":null
         },
         "images":{
            "detail":{
               "original":{
                  "size":90821,
                  "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-d-original.png",
                  "width":150,
                  "height":150
               }
            },
            "cover":{
               "original":{
                  "size":193141,
                  "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-c-original.png",
            "width":320,
                  "height":320
               }
            }
         },
         "name":"Starbucks"
      },
      ...
      ...
   ]
}