api: refactor pagination

* indexer: rename GetListAccounts -> AccountsList
* indexer: AccountsList now returns a TotalCount
* indexer: ProcessList now returns a TotalCount
* indexer: EntityList now returns a TotalCount

* test: add TestAPIAccountsList and TestAPIElectionsList

* api: unify hardcoded structs into a new types:
  * AccountsList
  * ElectionsList
  * OrganizationsList
  * CountResult

* api: add `total` field to endpoints:
  * GET /elections
  * GET /accounts
  * GET /chain/organizations

* api: refactor filtered endpoints to unify pagination logic, and add `total` field:
  * GET /accounts/{organizationID}/elections/status/{status}/page/{page}
  * GET /accounts/{organizationID}/elections/page/{page}
  * GET /elections/page/{page}
  * POST /elections/filter/page/{page}
  * GET /chain/organizations/page/{page}
  * POST /chain/organizations/filter/page/{page}
  * GET /accounts/page/{page}
also, marked all of these endpoints as deprecated on swagger docs

* deduplicate several code snippets, like params parsing and json.Marshal

* rename api.MaxPageSize -> api.ItemsPerPage

* fixed lots of swagger docs

api/api.go

@@ -47,8 +47,17 @@ import (
 
 //	@securityDefinitions.basic	BasicAuth
 
-// MaxPageSize defines the maximum number of results returned by the paginated endpoints
-const MaxPageSize = 10
+const (
+	// ItemsPerPage defines how many items per page are returned by the paginated endpoints
+	ItemsPerPage = 10
+
+	// These consts define the keywords for both query (?param=) and url (/url/param/) params
+	ParamPage           = "page"
+	ParamStatus         = "status"
+	ParamOrganizationID = "organizationID"
+	ParamElectionID     = "electionID"
+	ParamWithResults    = "withResults"
+)
 
 var (
 	ErrMissingModulesForHandler = fmt.Errorf("missing modules attached for enabling handler")

api/api_types.go

@@ -12,18 +12,23 @@ import (
 	"google.golang.org/protobuf/encoding/protojson"
 )
 
-type Organization struct {
-	OrganizationID types.HexBytes      `json:"organizationID,omitempty" `
-	Elections      []*ElectionSummary  `json:"elections,omitempty"`
-	Organizations  []*OrganizationList `json:"organizations,omitempty"`
-	Count          *uint64             `json:"count,omitempty" example:"1"`
+// CountResult wraps a count inside an object
+type CountResult struct {
+	Count uint64 `json:"count" example:"10"`
 }
 
-type OrganizationList struct {
+type OrganizationSummary struct {
 	OrganizationID types.HexBytes `json:"organizationID"  example:"0x370372b92514d81a0e3efb8eba9d036ae0877653"`
 	ElectionCount  uint64         `json:"electionCount" example:"1"`
 }
 
+// OrganizationList wraps the organizations list to consistently return the list inside an object,
+// and return an empty object if the list does not contains any result
+type OrganizationsList struct {
+	Organizations []OrganizationSummary `json:"organizations"`
+	Total         uint64                `json:"total"`
+}
+
 type ElectionSummary struct {
 	ElectionID     types.HexBytes    `json:"electionId" `
 	OrganizationID types.HexBytes    `json:"organizationId" `
@@ -37,6 +42,13 @@ type ElectionSummary struct {
 	ChainID        string            `json:"chainId"`
 }
 
+// ElectionsList wraps the elections list to consistently return the list inside an object,
+// and return an empty object if the list does not contains any result
+type ElectionsList struct {
+	Elections []ElectionSummary `json:"elections"`
+	Total     uint64            `json:"total"`
+}
+
 // ElectionResults is the struct used to wrap the results of an election
 type ElectionResults struct {
 	// ABIEncoded is the abi encoded election results
@@ -101,11 +113,16 @@ type ElectionDescription struct {
 }
 
 type ElectionFilter struct {
-	OrganizationID types.HexBytes `json:"organizationId,omitempty" `
-	ElectionID     types.HexBytes `json:"electionId,omitempty" `
+	Page           int            `json:"page,omitempty"`
+	OrganizationID types.HexBytes `json:"organizationId,omitempty"`
+	ElectionID     types.HexBytes `json:"electionId,omitempty"`
 	WithResults    *bool          `json:"withResults,omitempty"`
 	Status         string         `json:"status,omitempty"`
 }
+type OrganizationFilter struct {
+	Page           int            `json:"page,omitempty"`
+	OrganizationID types.HexBytes `json:"organizationId,omitempty"`
+}
 
 type Key struct {
 	Index int            `json:"index"`
@@ -228,6 +245,11 @@ type Account struct {
 	SIK           types.HexBytes   `json:"sik"`
 }
 
+type AccountsList struct {
+	Accounts []indexertypes.Account `json:"accounts"`
+	Total    uint64                 `json:"total"`
+}
+
 type AccountSet struct {
 	TxPayload   []byte         `json:"txPayload,omitempty" swaggerignore:"true"`
 	Metadata    []byte         `json:"metadata,omitempty" swaggerignore:"true"`

api/censuses.go

@@ -631,8 +631,10 @@ func (a *API) censusDeleteHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Security				BasicAuth
 //	@Success				200			{object}	object{census=object{censusID=string,uri=string}}	"It return published censusID and the ipfs uri where its uploaded"
 //	@Param					censusID	path		string												true	"Census id"
+//	@Param					root		path		string												false	"Specific root where to publish the census. Not required"
 //	@Router					/censuses/{censusID}/publish [post]
 //	@Router					/censuses/{censusID}/publish/async [post]
+//	@Router					/censuses/{censusID}/publish/{root} [post]
 func (a *API) censusPublishHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	token, err := uuid.Parse(msg.AuthToken)
 	if err != nil {
@@ -957,7 +959,7 @@ func (a *API) censusVerifyHandler(msg *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Accept			json
 //	@Produce		json
 //	@Success		200	{object}	object{valid=bool}
-//	@Router			/censuses/list/ [get]
+//	@Router			/censuses/list [get]
 func (a *API) censusListHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	list, err := a.censusdb.List()
 	if err != nil {
@@ -979,7 +981,8 @@ func (a *API) censusListHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext)
 //	@Produce		json
 //	@Param			ipfs	path		string	true	"Export to IPFS. Blank to return the JSON file"
 //	@Success		200		{object}	object{valid=bool}
-//	@Router			/censuses/export/{ipfs} [get]
+//	@Router			/censuses/export/ipfs [get]
+//	@Router			/censuses/export [get]
 func (a *API) censusExportDBHandler(_ *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	isIPFSExport := strings.HasSuffix(ctx.Request.URL.Path, "ipfs")
 	buf := bytes.Buffer{}
@@ -1012,7 +1015,8 @@ func (a *API) censusExportDBHandler(_ *apirest.APIdata, ctx *httprouter.HTTPCont
 //	@Accept			json
 //	@Produce		json
 //	@Success		200	{object}	object{valid=bool}
-//	@Router			/censuses/import/{ipfscid} [post]
+//	@Router			/censuses/import/{ipfscid} [get]
+//	@Router			/censuses/import [post]
 func (a *API) censusImportDBHandler(msg *apirest.APIdata, ctx *httprouter.HTTPContext) error {
 	ipfscid := ctx.URLParam("ipfscid")
 	if ipfscid == "" {