rest

README

Flow Access Node REST API Server

This package and subpackages implement the REST API Server for the Flow OpenAPI definition

Packages:

rest: The HTTP handlers for all the request, server generator and the select filter.

middleware: The common middlewares that all request pass through.

generate: The generated models from https://app.swaggerhub.com/ (note: only the generated models are included and not the api implementation since that part us custom)

Request lifecycle

1. Every incoming request passes through a common set of middlewares - logging middleware, query expandable and query select middleware defined in the middleware package.
2. A request is then sent to the handler.ServeHTTP function.
3. The handler.ServeHTTP function calls the appropriate ApiHandlerFunc handler function as defined in server.go e.g. getBlocksByIDs in blocks.go for a get blocks by IDs request or getBlocksByHeight for a get blocks by heights request etc.
4. Within the handler function, the request is first validated, then the necessary database lookups are performed and finally the appropriate response function is called. e.g. blockResponse for Block response.
5. After the response is generated, the select filter is applied if a select query param has been specified.
6. The Response is then sent to the client

Documentation

Index

• Constants
• Variables
• func CreateTransaction(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func ExecuteScript(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)
• func GetAccount(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetBlockPayloadByID(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)
• func GetBlocksByHeight(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetBlocksByIDs(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetCollectionByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetEvents(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)
• func GetExecutionResultByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetExecutionResultsByBlockIDs(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetTransactionByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func GetTransactionResultByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)
• func NewBlockProvider(backend access.API, options ...blockProviderOption) *blockProvider
• func NewServer(backend access.API, listenAddress string, logger zerolog.Logger, ...) (*http.Server, error)
• type ApiHandlerFunc
• type Error
  • func NewBadRequestError(err error) *Error
  • func NewNotFoundError(msg string, err error) *Error
  • func NewRestError(status int, msg string, err error) *Error
  • func (e *Error) Error() string
  • func (e *Error) Status() int
  • func (e *Error) UserMessage() string
• type Handler
  • func NewHandler(logger zerolog.Logger, backend access.API, handlerFunc ApiHandlerFunc, ...) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type StatusError

Constants

const (
	ExpandableFieldPayload    = "payload"
	ExpandableExecutionResult = "execution_result"
)

const MaxRequestSize = 2 << 20 // 2MB

Variables

var Routes = []route{{
	Method:  http.MethodGet,
	Pattern: "/transactions/{id}",
	Name:    "getTransactionByID",
	Handler: GetTransactionByID,
}, {
	Method:  http.MethodPost,
	Pattern: "/transactions",
	Name:    "createTransaction",
	Handler: CreateTransaction,
}, {
	Method:  http.MethodGet,
	Pattern: "/transaction_results/{id}",
	Name:    "getTransactionResultByID",
	Handler: GetTransactionResultByID,
}, {
	Method:  http.MethodGet,
	Pattern: "/blocks/{id}",
	Name:    "getBlocksByIDs",
	Handler: GetBlocksByIDs,
}, {
	Method:  http.MethodGet,
	Pattern: "/blocks",
	Name:    "getBlocksByHeight",
	Handler: GetBlocksByHeight,
}, {
	Method:  http.MethodGet,
	Pattern: "/blocks/{id}/payload",
	Name:    "getBlockPayloadByID",
	Handler: GetBlockPayloadByID,
}, {
	Method:  http.MethodGet,
	Pattern: "/execution_results/{id}",
	Name:    "getExecutionResultByID",
	Handler: GetExecutionResultByID,
}, {
	Method:  http.MethodGet,
	Pattern: "/execution_results",
	Name:    "getExecutionResultByBlockID",
	Handler: GetExecutionResultsByBlockIDs,
}, {
	Method:  http.MethodGet,
	Pattern: "/collections/{id}",
	Name:    "getCollectionByID",
	Handler: GetCollectionByID,
}, {
	Method:  http.MethodPost,
	Pattern: "/scripts",
	Name:    "executeScript",
	Handler: ExecuteScript,
}, {
	Method:  http.MethodGet,
	Pattern: "/accounts/{address}",
	Name:    "getAccount",
	Handler: GetAccount,
}, {
	Method:  http.MethodGet,
	Pattern: "/events",
	Name:    "getEvents",
	Handler: GetEvents,
}}

Functions

func CreateTransaction

func CreateTransaction(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

CreateTransaction creates a new transaction from provided payload.

func ExecuteScript

func ExecuteScript(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)

ExecuteScript handler sends the script from the request to be executed.

func GetAccount

func GetAccount(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetAccount handler retrieves account by address and returns the response

func GetBlockPayloadByID

func GetBlockPayloadByID(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)

GetBlockPayloadByID gets block payload by ID

func GetBlocksByHeight

func GetBlocksByHeight(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

func GetBlocksByIDs

func GetBlocksByIDs(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetBlocksByIDs gets blocks by provided ID or list of IDs.

func GetCollectionByID

func GetCollectionByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetCollectionByID retrieves a collection by ID and builds a response

func GetEvents

func GetEvents(r *request.Request, backend access.API, _ models.LinkGenerator) (interface{}, error)

GetEvents for the provided block range or list of block IDs filtered by type.

func GetExecutionResultByID

func GetExecutionResultByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetExecutionResultByID gets execution result by the ID.

func GetExecutionResultsByBlockIDs

func GetExecutionResultsByBlockIDs(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetExecutionResultsByBlockIDs gets Execution Result payload by block IDs.

func GetTransactionByID

func GetTransactionByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetTransactionByID gets a transaction by requested ID.

func GetTransactionResultByID

func GetTransactionResultByID(r *request.Request, backend access.API, link models.LinkGenerator) (interface{}, error)

GetTransactionResultByID retrieves transaction result by the transaction ID.

func NewBlockProvider

func NewBlockProvider(backend access.API, options ...blockProviderOption) *blockProvider

func NewServer

func NewServer(backend access.API, listenAddress string, logger zerolog.Logger, chain flow.Chain) (*http.Server, error)

NewServer returns an HTTP server initialized with the REST API handler

Types

type ApiHandlerFunc

type ApiHandlerFunc func(
	r *request.Request,
	backend access.API,
	generator models.LinkGenerator,
) (interface{}, error)

ApiHandlerFunc is a function that contains endpoint handling logic, it fetches necessary resources and returns an error or response model.

type Error

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

Error is implementation of status error.

func NewBadRequestError

func NewBadRequestError(err error) *Error

NewBadRequestError creates a new bad request rest error.

func NewNotFoundError

func NewNotFoundError(msg string, err error) *Error

NewNotFoundError creates a new not found rest error.

func NewRestError

func NewRestError(status int, msg string, err error) *Error

NewRestError creates an error returned to user with provided status user displayed message and internal error

func (*Error) Error

func (e *Error) Error() string

func (*Error) Status

func (e *Error) Status() int

Status returns error http status code.

func (*Error) UserMessage

func (e *Error) UserMessage() string

type Handler

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

Handler is custom http handler implementing custom handler function. Handler function allows easier handling of errors and responses as it wraps functionality for handling error and responses outside of endpoint handling.

func NewHandler

func NewHandler(
	logger zerolog.Logger,
	backend access.API,
	handlerFunc ApiHandlerFunc,
	generator models.LinkGenerator,
	chain flow.Chain,
) *Handler

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServerHTTP function acts as a wrapper to each request providing common handling functionality such as logging, error handling, request decorators

type StatusError

type StatusError interface {
	error                // this is the actual error that occured
	Status() int         // the HTTP status code to return
	UserMessage() string // the error message to return to the client
}

StatusError provides custom error with http status.