Merge pull request #683 from hermeznetwork/doc/api-and-sql-related

Add package level documentation for db, historydb, l2db, api, apitype…

api/api.go

@@ -1,3 +1,27 @@
+/*
+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.
+*/
 package api
 
 import (
@@ -28,7 +52,6 @@ func NewAPI(
 	l2db *l2db.L2DB,
 ) (*API, error) {
 	// Check input
-	// TODO: is stateDB only needed for explorer endpoints or for both?
 	if coordinatorEndpoints && l2db == nil {
 		return nil, tracerr.Wrap(errors.New("cannot serve Coordinator endpoints without L2DB"))
 	}
@@ -61,7 +84,7 @@ func NewAPI(
 
 	// Add coordinator endpoints
 	if coordinatorEndpoints {
-		// Account
+		// Account creation authorization
 		v1.POST("/account-creation-authorization", a.postAccountCreationAuth)
 		v1.GET("/account-creation-authorization/:hezEthereumAddress", a.getAccountCreationAuth)
 		// Transaction
@@ -79,17 +102,23 @@ func NewAPI(
 		// Transaction
 		v1.GET("/transactions-history", a.getHistoryTxs)
 		v1.GET("/transactions-history/:id", a.getHistoryTx)
-		// Status
+		// Batches
 		v1.GET("/batches", a.getBatches)
 		v1.GET("/batches/:batchNum", a.getBatch)
 		v1.GET("/full-batches/:batchNum", a.getFullBatch)
+		// Slots
 		v1.GET("/slots", a.getSlots)
 		v1.GET("/slots/:slotNum", a.getSlot)
+		// Bids
 		v1.GET("/bids", a.getBids)
+		// State
 		v1.GET("/state", a.getState)
+		// Config
 		v1.GET("/config", a.getConfig)
+		// Tokens
 		v1.GET("/tokens", a.getTokens)
 		v1.GET("/tokens/:id", a.getToken)
+		// Coordinators
 		v1.GET("/coordinators", a.getCoordinators)
 	}
 

api/apitypes/apitypes.go

@@ -1,3 +1,11 @@
+/*
+Package apitypes is used to map the common types used across the node with the format expected by the API.
+
+This is done using different strategies:
+- Marshallers: they get triggered when the API marshals the response structs into JSONs
+- Scanners/Valuers: they get triggered when a struct is sent/received to/from the SQL database
+- Adhoc functions: when the already mentioned strategies are not suitable, functions are added to the structs to facilitate the conversions
+*/
 package apitypes
 
 import (

api/stateapiupdater/stateapiupdater.go

@@ -1,3 +1,10 @@
+/*
+Package stateapiupdater is responsible for generating and storing the object response of the GET /state endpoint exposed through the api package.
+This object is extensively defined at the OpenAPI spec located at api/swagger.yml.
+
+Deployment considerations: in a setup where multiple processes are used (dedicated api process, separated coord / sync, ...), only one process should care
+of using this package.
+*/
 package stateapiupdater
 
 import (