Part 1: Using Python To Make API Requests To EOS Public API Endpoints

This tutorial is the first part of a series where different aspects of programming with EOS are explained. This part will explain how to find public api_endpoints and interact with them using Python.

---

Repository

https://github.com/EOSIO/eos

What will I learn

• Find a public API endpoint
• Perform GET requests
• Perform POST requests

Requirements

• Python3.6

Difficulty

• basic

---

Tutorial

Setup

Download the files from Github. There is 2 files get_info.py and get_block.py which takes 1 argument block_id.

Run scripts as following:
> python get_info.py
> python get_block.py 5

Find a public API endpoint

EOS uses 21 block producers(BP) which are known to everyone. There are network monitoring tools like the website eosnetworkmonitor where this information is published live.

However, finding the public api's for each BP requires a bit more digging. Every BP is required to host a file bp.json which can be found by taking their public url and adding /bp.json to it like bp.eosnewyork.io + \bp.json = bp.eosnewyork.io/bp.json. In this file at the bottom information about the api_endpoint is located. These api_endpoint's can be used to make API calls with for example python. In this example http://api.eosnewyork.io will be used in conjunction with Python.

{
  "producer_account_name": "eosnewyorkio",
  "producer_public_key": "EOS6GVX8eUqC1gN1293B3ivCNbifbr1BT6gzTFaQBXzWH9QNKVM4X",
  "org": {
    "candidate_name": "EOS New York",
    "website": "https://www.eosnewyork.io",
    "code_of_conduct": "https://steemit.com/eos/@eosnewyork/eos-new-york-code-of-conduct",
    "ownership_disclosure": "https://steemit.com/eos/@eosnewyork/eos-new-york-ownership-disclosure-and-corporate-structure",
    "email": "[email protected]",
    "branding": {
      "logo_256": "https://bp.eosnewyork.io/Logo_256.jpg",
      "logo_1024": "https://bp.eosnewyork.io/Logo_1024.jpg",
      "logo_svg": "https://bp.eosnewyork.io/eosnewyorkio.svg"
    },
    "location": {
      "name": "Cook Islands",
      "country": "CK",
      "latitude": -18.857952,
      "longitude": -159.785278
    },
    "social": {
      "steemit": "eosnewyork",
      "twitter": "eosnewyork",
      "youtube": "UCg7aeCSXUTP49w_elxgYIXA",
      "facebook": "eosnewyorkBP",
      "github": "eosnewyork",
      "reddit": "eosnewyork",
      "keybase": "d3ck",
      "telegram": "eosnewyorkchat",
      "wechat": "kevineosnewyork"
    }
  },
  "nodes": [
    {
      "location": {
        "name": "primary",
        "country": "BR",
        "latitude": -23.5505,
        "longitude": -46.6333
      },
      "is_producer": false,
      "node_type": "full",
      "p2p_endpoint": "node1.eosnewyork.io:6987",
      "api_endpoint": "http://api.eosnewyork.io",
      "ssl_endpoint": "https://api.eosnewyork.io"
    }
  ]
}

bp.eosnewyork.io/bp.json


Note: Not every BP has an api_endpoint

Perform GET requests

A full list of all possible API requests can be found here. They fall into one of two categories. GET and POST requests. To handle these API calls the requests library is used.

import requests

The url consists of the api_endpoint concatenated with the api_request. Performing a GET request returns a json structure which has to be decoded before printing.

api_endpoint = 'http://api.eosnewyork.io'
api_request = '/v1/chain/get_info'
url = api_endpoint + api_request

print(requests.get(url=url).json())

Perform POST requests

The difference between the a POST and a GET request is that for a POST data is posted to the server which then results into a text response. Normally a dictionary containing the variables would have been sufficient, however the EOS nodes only accept a string of the dict. In this example the dict {"block_num_or_id": <block_id> } is posted to the server. The parameters can be changed to retrieve different data.

block = int(sys.argv[1])
api_endpoint = 'http://api.eosnewyork.io'
api_request = '/v1/chain/get_block'
url = api_endpoint + api_request
parameters = '{"block_num_or_id":' + f'{block}' + '}'

print(requests.post(url=url, data=parameters).text)

Running the code

get_info.py performs the get_info API GET request and prints the result to the terminal.

python get_info.py
{
    'server_version': '36a043c5',
    'chain_id': 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
    'head_block_num': 4911490,
    'last_irreversible_block_num': 4911158,
    'last_irreversible_block_id': '004af036cb65d7c24ce811268bcf404631f27a9d5004a23001bee1679f1445ea',
    'head_block_id': '004af18275beff4a40c62baed070802fae40d1245cd11abea6d46b1df1efe223',
    'head_block_time': '2018-07-09T03:23:34.000',
    'head_block_producer': 'eoscanadacom',
    'virtual_block_cpu_limit': 200000000,
    'virtual_block_net_limit': 1048576000,
    'block_cpu_limit': 199900,
    'block_net_limit': 1048576
}

get_block.py takes 1 argument, the block_id and perform the API get_block POST request. Printing the requested block to the terminal.

python get_block.py 5
{
    "timestamp": "2018-06-09T11:56:31.500",
    "producer": "eosio",
    "confirmed": 0,
    "previous": "00000004faa09f2b6f59515121772032f080c12120d7e4b42c3b9569fb2a9a58",
    "transaction_mroot": "0000000000000000000000000000000000000000000000000000000000000000",
    "action_mroot": "40574fe525741beb36f4976e41ff902d1d31a684e53bcefefbf2e64648348108",
    "schedule_version": 0,
    "new_producers": null,
    "header_extensions": [],
    "producer_signature": "SIG_K1_K2j4PdYU28EJ5LAVeXxYjZY3uG1qtz4JF41sakGYPskpXDGotaen1A2sReh5dnHTTH1puZ5cMiGpGt2KTZBqTKCEHoJAr3",
    "transactions": [],
    "block_extensions": [],
    "id": "00000005c7424e57fd4fd8a6af3c612b1141c1dac23484c9258e7ecffcdbd5a6",
    "block_num": 5,
    "ref_block_prefix": 2799194109
}

---

The code for this tutorial can be found on GitHub!

This tutorial was written by @juliank.