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 the server generator and the select filter, implementation of handling local requests.
• common: Includes shared components for REST requests.
  • middleware: The common middlewares that all request pass through.
  • models: The common generated models using openapi generators.
• http: Implements core HTTP handling functionality for access node.
  • 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.
  • routes: The HTTP handlers for all http requests, tests for each request.
• router: Implementation of building HTTP routers with common middleware and routes.
• apiproxy: Implementation of proxy backend handler which includes the local backend and forwards the methods which can't be handled locally to an upstream using gRPC API. This is used by observers that don't have all data in their local db.

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/http/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 routes 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. If the data is not available on observers, an override the method is needed in the backend handler RestProxyHandler for request forwarding. 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
• func NewServer(serverAPI access.API, config Config, logger zerolog.Logger, chain flow.Chain, ...) (*http.Server, error)
• type Config

Constants

const (
	// DefaultReadTimeout is the default read timeout for the HTTP server
	DefaultReadTimeout = time.Second * 15

	// DefaultWriteTimeout is the default write timeout for the HTTP server
	DefaultWriteTimeout = time.Second * 30

	// DefaultIdleTimeout is the default idle timeout for the HTTP server
	DefaultIdleTimeout = time.Second * 60
)

Functions

func NewServer

func NewServer(serverAPI access.API,
	config Config,
	logger zerolog.Logger,
	chain flow.Chain,
	restCollector module.RestMetrics,
	stateStreamApi state_stream.API,
	stateStreamConfig backend.Config,
	wsConfig websockets.Config,
) (*http.Server, error)

NewServer returns an HTTP server initialized with the REST API handler

Types

type Config

type Config struct {
	ListenAddress  string
	WriteTimeout   time.Duration
	ReadTimeout    time.Duration
	IdleTimeout    time.Duration
	MaxRequestSize int64
}