api

README

Hermez API

Easy to deploy and scale API for Hermez operators. You will need to have docker and docker-compose installed on your machine in order to use this repo.

Documentation

As of now the documentation is not hosted anywhere, but you can easily do it yourself by running ./run.sh doc and then opening the documentation in your browser

Mock Up

To use a mock up of the endpoints in the API run ./run.sh doc (UI + mock up server) or ./run.sh mock (only mock up server). You can play with the mocked up endpoints using the web UI, importing swagger.yml into Postman or using your preferred language and using http://localhost:4010 as base URL.

Editor

It is recomended to edit swagger.yml using a dedicated editor as they provide spec validation and real time visualization. Of course you can use your prefered editor. To use the editor run ./run.sh editor and then opening the editor in your browser. Keep in mind that you will need to manually save the file otherwise you will lose the changes you made once you close your browser seshion or stop the server.

Note: Your browser may cache the swagger definition, so in order to see updated changes it may be needed to refresh the page without cache (Ctrl + Shift + R).

Documentation

Overview

Package api implements the public interface of the hermez-node using a HTTP REST API. There are two subsets of endpoints: - coordinatorEndpoints: used to receive L2 transactions and account creation authorizations. Targeted for wallets. - explorerEndpoints: used to provide all sorts of information about the network. Targeted for explorers and similar services.

About the configuration of the API: - The API is supposed to be launched using the cli found at the package cli/node, and configured through the configuration file. - The mentioned configuration file allows exposing any combination of the endpoint subsets. - Although the API can run in a "standalone" manner using the serveapi command, it won't work properly unless another process acting as a coord or sync is filling the HistoryDB.

Design principles and considerations: - In order to decouple the API process from the rest of the node, all the communication between this package and the rest of the system is done through the SQL database. As a matter of fact, the only public function of the package is the constructor NewAPI. All the information needed for the API to work should be obtained through the configuration file of the cli or the database. - The format of the requests / responses doesn't match directly with the common types, and for this reason, the package api/apitypes is used to facilitate the format conversion. Most of the time, this is done directly at the db level. - The API endpoints are fully documented using OpenAPI aka Swagger. All the endpoints are tested against the spec to ensure consistency between implementation and specification. To get a sense of which endpoints exist and how they work, it's strongly recommended to check this specification. The specification can be found at api/swagger.yml. - In general, all the API endpoints produce queries to the SQL database in order to retrieve / insert the requested information. The most notable exceptions to this are the /config endpoint, which returns a static object generated at construction time, and the /state, which also is retrieved from the database, but it's generated by API/stateapiupdater package.

Index

• Constants
• type API
  • func NewAPI(version string, coordinatorEndpoints, explorerEndpoints bool, ...) (*API, error)
• type Config
• type SlotAPI

Constants

const (

	// ErrDuplicatedKey error message returned when trying to insert an item with duplicated key
	ErrDuplicatedKey = "Item already exists"
	// ErrSQLTimeout error message returned when timeout due to SQL connection
	ErrSQLTimeout = "The node is under heavy preasure, please try again later"
	// ErrExitAmount0 error message returned when receiving (and rejecting) a tr of type exit with amount 0
	ErrExitAmount0 = "Transaction rejected because an exit with amount 0 has no sense"
)

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API serves HTTP requests to allow external interaction with the Hermez node

func NewAPI

func NewAPI(
	version string,
	coordinatorEndpoints, explorerEndpoints bool,
	server *gin.Engine,
	hdb *historydb.HistoryDB,
	l2db *l2db.L2DB,
) (*API, error)

NewAPI sets the endpoints and the appropriate handlers, but doesn't start the server

type Config

type Config struct {
	RollupConstants   common.RollupConstants
	AuctionConstants  common.AuctionConstants
	WDelayerConstants common.WDelayerConstants
	ChainID           uint16
	HermezAddress     ethCommon.Address
}

Config of the API

type SlotAPI

type SlotAPI struct {
	ItemID      uint64            `json:"itemId"`
	SlotNum     int64             `json:"slotNum"`
	FirstBlock  int64             `json:"firstBlock"`
	LastBlock   int64             `json:"lastBlock"`
	OpenAuction bool              `json:"openAuction"`
	WinnerBid   *historydb.BidAPI `json:"bestBid"`
}

SlotAPI is a representation of a slot information