apidirectory, a catalog of EOSIO API endpoints

cc32d9
cc32d9
Mar 11 · 3 min read

Here’s my weekend project. The idea popped up last Friday when discussing the new Hyperion API on Telegram. There should be a way for API providers to list themselves in a kind of directory, like I did for my Light API. But that’s a directory specific for the API, which is inconvenient.

So, now we have a smart contract that registers all possible API services for all EOSIO-based blockchains:

The smart contract is already deployed on mainnet. If you are hosting an API, here are simple steps to register using cleos. The first command sets a shell alias to shorten further commands. Then you send setprovider action and describe yourself.

alias cl='cleos -v -u https://api.eossweden.se'

At this point your entry in providers table has the field “approved”: 0 and it requires an approval from the admins team. I haven’t yet figured out a better way to avoid spamming. If nobody from the admin team (which consists of only myself currently :)) recognizes you, they will contact you to check who you are. Then they will push an approval action.

Once approved, you can describe all your API endpoints in the catalog. The action updrec either creates a new record, or updates an existing one (Attention: if the record is audited, the new update will clear the audit report. See details below).

You need to supply the following attributes for a record:

  • network: a network name as listed in networks table. EOS Mainnet goes as eos. There are also all other networks that I know of, like telos, worbli, jungle, etc. See the README on GitHub for the full list.
  • type: the API type. I listed a few in apitypes table, and there will be more.
  • provider: your EOS mainnet account name.
  • srvname: service name, up to 13 characters in EOS account format ([a-z1–5]{1,12}, with a possible dot, or an empty string). You are totally free to design your naming schema for it. It will be used for referring to your API endpoints in further updates. If you only have one one endpoint of given type for a given network, you can use empty string here.
  • url: the API endpoint URL. Depending on the type of API, this can be a full HTTP(s) URL, or host:port for an API like p2p interface in nodeos.
  • continent: ISO code of the continent your API is served from ( “AF”, “AN”, “AS”, “EU”, “NA”, “OC”, “SA”), or “ANY” if you have a georedundant setup across multiple continents.
  • country: ISO code of the country the API is served from, or “ANY” for georedundant setup.
  • flags: an integer which is zero in most cases. It indicates implementation options for some API types. For example, there are several different implementations of EOS History API.

Here’s an example of EOS USA listing their P2P interface:

cl push action apidirectory updrec '["eos", "p2p", "ivote4eosusa", "eosusse1", "seed01.eosusa.news:9876", "NA", "US", 0]' -p ivote4eosusa@active

There is no web user interface for the catalog yet. If you intend to build one, please contact me on Telegram: cc32d9

One of possible uses for the directory is rewarding the public service providers. That requires an auditing process that verifies the service ownership and functionality. So, the smart contract allows registering auditors which will verify the records and submit audit reports. The reports will be stored on IPFS, and the records will have links to IPFS documents. Each audit report would refer to a particular revision of the record, and audited status would be cleared once the record is updated by the provider. reports are signed by auditor PGP keys. The mechanics for auditing are already in the contract, and the file format for the audit reports is yet to be developed. Most probably that will be JSON or YAML document.

cc32d9

Written by

cc32d9

ETH address: "0x7137bfe007B15F05d3BF7819d28419EAFCD6501E" EOS account: "cc32dninexxx"