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
• func NewBlockProvider(backend access.API, options ...blockProviderOption) *blockProvider
• func NewServer(backend access.API, listenAddress string, logger zerolog.Logger) *http.Server
• func SelectFilter(object interface{}, selectKeys []string) (interface{}, error)
• type ApiHandlerFunc
• type Handler
  • func NewHandler(logger zerolog.Logger, backend access.API, handlerFunc ApiHandlerFunc, ...) *Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type LinkFunc
• type LinkGenerator
• type LinkGeneratorImpl
  • func NewLinkGeneratorImpl(router *mux.Router) *LinkGeneratorImpl
  • func (generator *LinkGeneratorImpl) AccountLink(address string) (string, error)
  • func (generator *LinkGeneratorImpl) BlockLink(id flow.Identifier) (string, error)
  • func (generator *LinkGeneratorImpl) CollectionLink(id flow.Identifier) (string, error)
  • func (generator *LinkGeneratorImpl) ExecutionResultLink(id flow.Identifier) (string, error)
  • func (generator *LinkGeneratorImpl) PayloadLink(id flow.Identifier) (string, error)
  • func (generator *LinkGeneratorImpl) TransactionLink(id flow.Identifier) (string, error)
  • func (generator *LinkGeneratorImpl) TransactionResultLink(id flow.Identifier) (string, error)
• type RestError
  • func NewBadRequestError(err error) *RestError
  • func NewNotFoundError(msg string, err error) *RestError
  • func NewRestError(status int, msg string, err error) *RestError
  • func (e *RestError) Error() string
  • func (e *RestError) Status() int
  • func (e *RestError) UserMessage() string
• type StatusError
  • func NotImplemented(_ *request, _ access.API, _ LinkGenerator) (interface{}, StatusError)

Examples

• SelectFilter

Constants

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

const MaxAllowedHeights = 50

const MaxAllowedIDs = 50

Functions

func NewBlockProvider

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

func NewServer

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

NewServer returns an HTTP server initialized with the REST API handler

func SelectFilter

func SelectFilter(object interface{}, selectKeys []string) (interface{}, error)

SelectFilter selects the specified keys from the given object. The keys are in the json dot notation and must refer to leaf elements e.g. payload.collection_guarantees.signer_ids

Example

blocks := make([]generated.Block, 2)
for i := range blocks {
	block, err := generateBlock()
	if err != nil {
		fmt.Println(err)
		return
	}
	blocks[i] = block
}

selectKeys := []string{
	"header.id",
	"payload.collection_guarantees.signature",
	"payload.block_seals.aggregated_approval_signatures.signer_ids",
	"payload.collection_guarantees.signer_ids",
	"execution_result.events.event_index",
	"something.nonexisting",
}

filteredBlock, err := SelectFilter(blocks, selectKeys)
if err != nil {
	fmt.Println(err)
	return
}

marshalled, err := json.MarshalIndent(filteredBlock, "", "\t")
if err != nil {
	panic(err.Error())
}
fmt.Println(string(marshalled))

Output:

[
	{
		"execution_result": {
			"events": [
				{
					"event_index": "2"
				},
				{
					"event_index": "3"
				}
			]
		},
		"header": {
			"id": "abcd"
		},
		"payload": {
			"block_seals": [
				{
					"aggregated_approval_signatures": [
						{
							"signer_ids": [
								"abcdef0123456789",
								"abcdef0123456789"
							]
						}
					]
				}
			],
			"collection_guarantees": [
				{
					"signature": "abcdef0123456789",
					"signer_ids": [
						"abcdef0123456789",
						"abcdef0123456789"
					]
				}
			]
		}
	},
	{
		"execution_result": {
			"events": [
				{
					"event_index": "2"
				},
				{
					"event_index": "3"
				}
			]
		},
		"header": {
			"id": "abcd"
		},
		"payload": {
			"block_seals": [
				{
					"aggregated_approval_signatures": [
						{
							"signer_ids": [
								"abcdef0123456789",
								"abcdef0123456789"
							]
						}
					]
				}
			],
			"collection_guarantees": [
				{
					"signature": "abcdef0123456789",
					"signer_ids": [
						"abcdef0123456789",
						"abcdef0123456789"
					]
				}
			]
		}
	}
]

Types

type ApiHandlerFunc

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

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

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 LinkGenerator) *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 LinkFunc

type LinkFunc func(id flow.Identifier) (string, error)

type LinkGenerator

type LinkGenerator interface {
	BlockLink(id flow.Identifier) (string, error)
	TransactionLink(id flow.Identifier) (string, error)
	TransactionResultLink(id flow.Identifier) (string, error)
	PayloadLink(id flow.Identifier) (string, error)
	ExecutionResultLink(id flow.Identifier) (string, error)
	AccountLink(address string) (string, error)
	CollectionLink(id flow.Identifier) (string, error)
}

LinkGenerator generates the expandable value for the known endpoints e.g. "/v1/blocks/c5e935bc75163db82e4a6cf9dc3b54656709d3e21c87385138300abd479c33b7"

type LinkGeneratorImpl

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

func NewLinkGeneratorImpl

func NewLinkGeneratorImpl(router *mux.Router) *LinkGeneratorImpl

func (*LinkGeneratorImpl) AccountLink

func (generator *LinkGeneratorImpl) AccountLink(address string) (string, error)

func (*LinkGeneratorImpl) BlockLink

func (generator *LinkGeneratorImpl) BlockLink(id flow.Identifier) (string, error)

func (*LinkGeneratorImpl) CollectionLink

func (generator *LinkGeneratorImpl) CollectionLink(id flow.Identifier) (string, error)

func (*LinkGeneratorImpl) ExecutionResultLink

func (generator *LinkGeneratorImpl) ExecutionResultLink(id flow.Identifier) (string, error)

func (*LinkGeneratorImpl) PayloadLink

func (generator *LinkGeneratorImpl) PayloadLink(id flow.Identifier) (string, error)

func (*LinkGeneratorImpl) TransactionLink

func (generator *LinkGeneratorImpl) TransactionLink(id flow.Identifier) (string, error)

func (*LinkGeneratorImpl) TransactionResultLink

func (generator *LinkGeneratorImpl) TransactionResultLink(id flow.Identifier) (string, error)

type RestError

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

RestError is implementation of status error.

func NewBadRequestError

func NewBadRequestError(err error) *RestError

NewBadRequestError creates a new bad request rest error.

func NewNotFoundError

func NewNotFoundError(msg string, err error) *RestError

NewNotFoundError creates a new not found rest error.

func NewRestError

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

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

func (*RestError) Error

func (e *RestError) Error() string

func (*RestError) Status

func (e *RestError) Status() int

Status returns error http status code.

func (*RestError) UserMessage

func (e *RestError) UserMessage() string

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.

func NotImplemented

func NotImplemented(
	_ *request,
	_ access.API,
	_ LinkGenerator,
) (interface{}, StatusError)

NotImplemented handler returns an error explaining the endpoint is not yet implemented