Merge branches 'feat/api-refactor-pagination' and 'feat/index-blocks'…

… into dev

api/api.go

@@ -1,10 +1,7 @@
 package api
 
-////// Disabled autoswag due to https://github.com/swaggo/swag/issues/1267
-////// TODO: re-enable when a fixed swaggo/swag is released
-////// and remove the workaround done by @selankon on docs/models/models.go
-////go:generate go run go.vocdoni.io/dvote/api/autoswag
-//go:generate go run github.com/swaggo/swag/cmd/[email protected] fmt
+//go:generate go run go.vocdoni.io/dvote/api/autoswag
+//go:generate go run github.com/swaggo/swag/cmd/[email protected] fmt
 
 import (
 	"fmt"
@@ -50,8 +47,30 @@ import (
 
 //	@securityDefinitions.basic	BasicAuth
 
-// MaxPageSize defines the maximum number of results returned by the paginated endpoints
-const MaxPageSize = 10
+const (
+	// DefaultItemsPerPage defines how many items per page are returned by the paginated endpoints,
+	// when the client doesn't specify a `limit` param
+	DefaultItemsPerPage = 10
+	// MaxItemsPerPage defines a ceiling for the `limit` param passed by the client
+	MaxItemsPerPage = 100
+)
+
+// These consts define the keywords for query (?param=), url (/url/param/) and POST params.
+// Note: In JS/TS acronyms like "ID" are camelCased as in "Id".
+//
+//nolint:revive
+const (
+	ParamAccountId      = "accountId"
+	ParamCensusId       = "censusId"
+	ParamElectionId     = "electionId"
+	ParamOrganizationId = "organizationId"
+	ParamVoteId         = "voteId"
+	ParamPage           = "page"
+	ParamLimit          = "limit"
+	ParamStatus         = "status"
+	ParamWithResults    = "withResults"
+	ParamHeight         = "height"
+)
 
 var (
 	ErrMissingModulesForHandler = fmt.Errorf("missing modules attached for enabling handler")

api/api_types.go

@@ -12,18 +12,74 @@ 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"`
+// ### Params accepted ###
+
+// PaginationParams allows the client to request a specific page, and how many items per page
+type PaginationParams struct {
+	Page  int `json:"page,omitempty"`
+	Limit int `json:"limit,omitempty"`
+}
+
+// ElectionParams allows the client to filter elections results
+type ElectionParams struct {
+	PaginationParams
+	OrganizationID types.HexBytes `json:"organizationId,omitempty"`
+	ElectionID     types.HexBytes `json:"electionId,omitempty"`
+	WithResults    bool           `json:"withResults,omitempty"`
+	Status         string         `json:"status,omitempty"`
+}
+
+// OrganizationParams allows the client to filter organizations results
+type OrganizationParams struct {
+	PaginationParams
+	OrganizationID types.HexBytes `json:"organizationId,omitempty"`
+}
+
+// AccountParams allows the client to filter accounts results
+type AccountParams struct {
+	PaginationParams
+}
+
+// TransactionParams allows the client to filter transactions results
+type TransactionParams struct {
+	PaginationParams
+	Height uint64 `json:"height,omitempty"`
+}
+
+// VoteParams allows the client to filter votes
+type VoteParams struct {
+	PaginationParams
+	ElectionID types.HexBytes `json:"electionId,omitempty"`
+}
+
+// ### Objects returned ###
+
+// CountResult wraps a count inside an object
+type CountResult struct {
+	Count uint64 `json:"count" example:"10"`
 }
 
-type OrganizationList struct {
+// Pagination contains all the values needed for the UI to easily organize the returned data
+type Pagination struct {
+	TotalItems   uint64  `json:"totalItems"`
+	PreviousPage *uint64 `json:"previousPage"`
+	CurrentPage  uint64  `json:"currentPage"`
+	NextPage     *uint64 `json:"nextPage"`
+	LastPage     uint64  `json:"lastPage"`
+}
+
+type OrganizationSummary struct {
 	OrganizationID types.HexBytes `json:"organizationID"  example:"0x370372b92514d81a0e3efb8eba9d036ae0877653"`
 	ElectionCount  uint64         `json:"electionCount" example:"1"`
 }
 
+// OrganizationsList 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"`
+	Pagination    *Pagination           `json:"pagination"`
+}
+
 type ElectionSummary struct {
 	ElectionID     types.HexBytes    `json:"electionId" `
 	OrganizationID types.HexBytes    `json:"organizationId" `
@@ -37,6 +93,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"`
+	Pagination *Pagination       `json:"pagination"`
+}
+
 // ElectionResults is the struct used to wrap the results of an election
 type ElectionResults struct {
 	// ABIEncoded is the abi encoded election results
@@ -100,13 +163,6 @@ type ElectionDescription struct {
 	TempSIKs     bool                  `json:"tempSIKs"`
 }
 
-type ElectionFilter struct {
-	OrganizationID types.HexBytes `json:"organizationId,omitempty" `
-	ElectionID     types.HexBytes `json:"electionId,omitempty" `
-	WithResults    *bool          `json:"withResults,omitempty"`
-	Status         string         `json:"status,omitempty"`
-}
-
 type Key struct {
 	Index int            `json:"index"`
 	Key   types.HexBytes `json:"key" `
@@ -115,7 +171,9 @@ type Key struct {
 type Vote struct {
 	TxPayload []byte         `json:"txPayload,omitempty"  extensions:"x-omitempty" swaggerignore:"true"`
 	TxHash    types.HexBytes `json:"txHash,omitempty"  extensions:"x-omitempty" `
-	VoteID    types.HexBytes `json:"voteID,omitempty"  extensions:"x-omitempty" `
+	// VoteID here produces a `voteID` over JSON that differs in casing from the rest of params and JSONs
+	// but is kept for backwards compatibility
+	VoteID types.HexBytes `json:"voteID,omitempty"  extensions:"x-omitempty" `
 	// Sent only for encrypted elections (no results until the end)
 	EncryptionKeyIndexes []uint32 `json:"encryptionKeys,omitempty" extensions:"x-omitempty"`
 	// For encrypted elections this will be codified
@@ -131,6 +189,11 @@ type Vote struct {
 	Date *time.Time `json:"date,omitempty" extensions:"x-omitempty"`
 }
 
+type VotesList struct {
+	Votes      []Vote      `json:"votes"`
+	Pagination *Pagination `json:"pagination"`
+}
+
 type CensusTypeDescription struct {
 	Type      string         `json:"type"`
 	Size      uint64         `json:"size"`
@@ -180,13 +243,22 @@ type TransactionReference struct {
 	Index  uint32 `json:"transactionIndex"`
 }
 
+// TODO: remove this struct, indexertypes.Transaction is the same but includes blockHeight which is great
 type TransactionMetadata struct {
 	Type   string         `json:"transactionType"`
 	Number uint32         `json:"transactionNumber"`
 	Index  int32          `json:"transactionIndex"`
 	Hash   types.HexBytes `json:"transactionHash" `
 }
 
+// TransactionsList wraps the transactions list to consistently return the list inside an object,
+// and return an empty object if the list does not contains any result
+type TransactionsList struct {
+	Transactions []indexertypes.Transaction `json:"transactions"`
+	Pagination   *Pagination                `json:"pagination"`
+}
+
+// TODO: this struct should be deprecated, why blockNumber instead of blockHeight??
 type BlockTransactionsInfo struct {
 	BlockNumber       uint64                `json:"blockNumber"`
 	TransactionsCount uint32                `json:"transactionCount"`
@@ -229,6 +301,11 @@ type Account struct {
 	SIK           types.HexBytes   `json:"sik"`
 }
 
+type AccountsList struct {
+	Accounts   []indexertypes.Account `json:"accounts"`
+	Pagination *Pagination            `json:"pagination"`
+}
+
 type AccountSet struct {
 	TxPayload   []byte         `json:"txPayload,omitempty" swaggerignore:"true"`
 	Metadata    []byte         `json:"metadata,omitempty" swaggerignore:"true"`
@@ -237,6 +314,8 @@ type AccountSet struct {
 }
 
 type Census struct {
+	// CensusID here produces a `censusID` over JSON that differs in casing from the rest of params and JSONs
+	// but is kept for backwards compatibility
 	CensusID types.HexBytes `json:"censusID,omitempty"`
 	Type     string         `json:"type,omitempty"`
 	Weight   *types.BigInt  `json:"weight,omitempty"`
@@ -339,4 +418,5 @@ func CensusTypeToOrigin(ctype CensusTypeDescription) (models.CensusOrigin, []byt
 type Block struct {
 	comettypes.Block `json:",inline"`
 	Hash             types.HexBytes `json:"hash" `
+	TxCount          int64          `json:"txCount"`
 }