README.md

Factom Open API

Factom Open API is a lightweight REST API for the Factom blockchain. It connects to an existing factomd node and has a built-in Factom wallet that will handle signing data before writing it to the Factom blockchain.

Main features

• Instant start: use Open API immediately after installation
• Write data to the blockchain
• Users: user-based API access, counting usage, limits
• Read all chain entries at once using a single request (no need to read all entry blocks of chain one by one)
• Search chains & entries by tags (external IDs)
• Pagination, sorting, filtering results with query params
• Generic factomd interface: all factomd API requests are supported via special REST path

API Reference

Documentation

• Documentation on Gitbook: https://docs.openapi.de-facto.pro
• Built-in Swagger specification: http://<factom_open_api_server_ip_and_port>/docs/index.html

Methods

• Chains
  • POST /chains – Create chain
  • GET /chains – Get user's chains
  • POST /chains/search – Search user's chains by ExtIDs
  • GET /chains/:chainId – Get chain by ChainID
  • GET /chains/:chainId/entries – Get chain entries
  • GET /chains/:chainId/entries/first – Get first entry of chain
  • GET /chains/:chainId/entries/last – Get last entry of chain
  • POST /chains/:chainId/entries/search – Search entries in chain by ExtIDs
• Entries
  • POST /entries – Create entry in chain
  • GET /entries/:entryHash – Get entry by EntryHash
• Generic
  • POST /factomd/:method – Generic factomd interface
• Info
  • GET /user – Get user info
  • GET / – Get API info

Installation guides

• 🐳 Install with Docker
• 🛠 Install with binaries

Entry Credits

Entry Credits (EC) purchase fixed amounts of data in the Factom network.
You need EC address filled with Entry Credits to write data on the Factom.

• EC address may be imported or generated via Open API Admin UI
  
• Fund your EC address in the EC store

Design

Fetching updates

Factom Open API does not store all chains of the Factom blockchain in its local database. Instead, when you start working with a chain using any request (get entry of chain, get chain info, write entry into chain, etc...), the chain is fetched from Factom in the background.

All fetched chains are stored in the local DB, and new entries are added automatically in minute 0-1 of each block.

This allows Factom Open API to be used immediately after installing without a long syncing period with Factom blockchain. It is not designed for applications which require all chains, blocks and entries - e.g. a Factom Explorer.

User's chains

A great advantage of Factom Open API is binding chains to API users. This binding is stored locally in the Open API database. It's possible to show users their chains, including ones the user created and all chains that the user has worked with (write, read or search).

This way API users may search their specific chains by External ID(s) instead of searching the entire blockchain.

License

Factom Open API is released under the MIT License.