rest

package
v0.31.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 6, 2023 License: AGPL-3.0 Imports: 26 Imported by: 2

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

View Source 
const (
	ExpandableFieldPayload    = "payload"
	ExpandableExecutionResult = "execution_result"
)
View Source 
const MaxRequestSize = 2 << 20 // 2MB

Variables

View Source 
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,
}, {
	Method:  http.MethodGet,
	Pattern: "/node_version_info",
	Name:    "getNodeVersionInfo",
	Handler: GetNodeVersionInfo,
}}

Functions

func CreateTransaction added in v0.23.9 

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

CreateTransaction creates a new transaction from provided payload.

func ExecuteScript added in v0.23.9 

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 added in v0.23.9 

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 added in v0.23.9 

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

GetBlockPayloadByID gets block payload by ID

func GetBlocksByHeight added in v0.23.9 

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

func GetBlocksByIDs added in v0.23.9 

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 added in v0.23.9 

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 added in v0.23.9 

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 added in v0.23.9 

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

GetExecutionResultByID gets execution result by the ID.

func GetExecutionResultsByBlockIDs added in v0.23.9 

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

GetExecutionResultsByBlockIDs gets Execution Result payload by block IDs.

func GetNetworkParameters added in v0.28.0 

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

GetNetworkParameters returns network-wide parameters of the blockchain

func GetNodeVersionInfo added in v0.31.0 

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

GetNodeVersionInfo returns node version information

func GetTransactionByID added in v0.23.9 

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

GetTransactionByID gets a transaction by requested ID.

func GetTransactionResultByID added in v0.23.9 

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

GetTransactionResultByID retrieves transaction result by the transaction ID.

func NewBlockProvider added in v0.23.5 

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

func NewServer 

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

NewServer returns an HTTP server initialized with the REST API handler

Types

type ApiHandlerFunc added in v0.23.5 

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 added in v0.23.9 

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

Error is implementation of status error.

func NewBadRequestError added in v0.23.5 

func NewBadRequestError(err error) *Error

NewBadRequestError creates a new bad request rest error.

func NewNotFoundError added in v0.23.5 

func NewNotFoundError(msg string, err error) *Error

NewNotFoundError creates a new not found rest error.

func NewRestError added in v0.23.5 

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 added in v0.23.9 

func (e *Error) Error() string

func (*Error) Status added in v0.23.9 

func (e *Error) Status() int

Status returns error http status code.

func (*Error) UserMessage added in v0.23.9 

func (e *Error) UserMessage() string

type Handler added in v0.23.5 

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 added in v0.23.5 

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

func (*Handler) ServeHTTP added in v0.23.5 

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 added in v0.23.5 

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.

Source Files

View all Source files

Directories

Path Synopsis
* Access API * * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen) * * API version: 1.0.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)
 * Access API * * No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen) * * API version: 1.0.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.