rest

README

Flow Access Node HTTP API Server

This package and subpackages implement the HTTP API Server for the Flow OpenAPI definition. The API documentation is available on our docs site.

Packages

• rest: The HTTP handlers for all the request, server generator and the select filter.
• middleware: The common middlewares that all request pass through.
• models: The generated models using openapi generators and implementation of model builders.
• request: Implementation of API requests that provide validation for input data and build request models.

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. Each request is then wrapped by our handler (rest/handler.go) and request input data is used to build the request models defined in request package.
3. The request is then sent to the corresponding API handler based on the configuration in the router.
4. Each handler implements actions to perform the request (database lookups etc) and after the response is built using the model builders defined in models package.
5. Returned value is then again handled by our wrapped handler making sure to correctly handle successful and failure responses.

Maintaining

Updating OpenAPI Schema

Make sure the OpenAPI schema if first updated and merged into master on the hosted repository. After you can use the make command to generated updated models:

make generate-openapi

Adding New API Endpoints

A new endpoint can be added by first implementing a new request handler, a request handle is a function in the rest package that complies with function interfaced defined as:

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

That handler implementation needs to be added to the router.go with corresponding API endpoint and method. Adding a new API endpoint also requires for a new request builder to be implemented and added in request package. Make sure to not forget about adding tests for each of the API handler.

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 GetNetworkParameters(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,
}, {
	Method:  http.MethodGet,
	Pattern: "/network/parameters",
	Name:    "getNetworkParameters",
	Handler: GetNetworkParameters,
}}

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 GetNetworkParameters

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

GetNetworkParameters returns network-wide parameters of the blockchain

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.