api

README

Oasis Nexus API

The Oasis Nexus API follows the OpenAPI 3.0 Specification for API documentation.

Render

You can render the OpenAPI docs from the repository root with

make docs-api

Documentation

Index

• Variables
• func FixDefaultsAndLimitsMiddleware(next apiTypes.StrictHandlerFunc, _operationID string) apiTypes.StrictHandlerFunc
• func HttpCodeForError(err error) int
• func HumanReadableJsonErrorHandler(w http.ResponseWriter, r *http.Request, err error)
• func MetricsMiddleware(m metrics.RequestMetrics, logger log.Logger) func(next http.Handler) http.Handler
• func ParseBigIntParamsMiddleware(next apiTypes.StrictHandlerFunc, _operationID string) apiTypes.StrictHandlerFunc
• func RuntimeFromURLMiddleware(baseURL string) func(next http.Handler) http.Handler
• type ErrStorageError
  • func (e ErrStorageError) Error() string

Variables

var (
	// ErrBadRequest is returned when the provided HTTP request
	// is malformed.
	ErrBadRequest = errors.New("invalid request parameters")
	// ErrBadChainID is returned when a malformed or missing chain ID
	// is provided.
	ErrBadChainID = errors.New("unable to resolve chain ID")
	// ErrBadRuntime is returned when a malformed or missing runtime name
	// is provided.
	ErrBadRuntime = errors.New("unable to resolve runtime")
	// ErrNotFound is returned when handling a request for an item that
	// does not exist in the DB.
	ErrNotFound = errors.New("item not found")
)

var CorsMiddleware func(http.Handler) http.Handler = cors.New(cors.Options{
	AllowedMethods: []string{
		http.MethodGet,
	},
	AllowCredentials: false,
}).Handler

CorsMiddleware is a restrictive CORS middleware that only allows GET requests.

NOTE: To support other methods (e.g. POST), we'd also need to support OPTIONS preflight requests, in which case this would have to be the outermost handler to run; the openapi-generated handler will reject OPTIONS requests because they are not in the openapi spec.

Functions

func FixDefaultsAndLimitsMiddleware

func FixDefaultsAndLimitsMiddleware(next apiTypes.StrictHandlerFunc, _operationID string) apiTypes.StrictHandlerFunc

FixDefaultsAndLimits modifies pagination parameters of the request in-place: If they're missing, it assigns them default values, and if they exist, it clamps them within the allowed limits. Both of these should be done by oapi-codegen, but it doesn't do it yet.

_operationID is unused, but is required to match the StrictHandlerFunc signature. It takes values like "GetConsensusTransactions".

func HttpCodeForError

func HttpCodeForError(err error) int

func HumanReadableJsonErrorHandler

func HumanReadableJsonErrorHandler(w http.ResponseWriter, r *http.Request, err error)

A simple error handler that renders any error as human-readable JSON to the HTTP response stream `w`.

func MetricsMiddleware

func MetricsMiddleware(m metrics.RequestMetrics, logger log.Logger) func(next http.Handler) http.Handler

MetricsMiddleware is a middleware that measures the start and end of each request, as well as other useful request information. It should be used as the outermost middleware, so it can - set a requestID and make it available to all handlers and - observe the final HTTP status code at the end of the request.

func ParseBigIntParamsMiddleware

func ParseBigIntParamsMiddleware(next apiTypes.StrictHandlerFunc, _operationID string) apiTypes.StrictHandlerFunc

ParseBigIntParamsMiddleware fixes the parsing of URL query parameters of type *BigInt. oapi-codegen does not really support reading URL query params into structs (but see note below). This middleware reproduces a portion of oapi-codegen's param-fetching logic, but then parses the input string with `UnmarshalText()`.

LIMITATIONS: The middleware relies on assumptions that happen to hold for nexus:

• only works for `*BigInt` (not `BigInt`)
• only works for `*BigInt` fields directly under `Params`, not nested in other structs.
• only works for URL query parameters (like ?myNumber=123), not path parameters (like .../foo/123?...) or HTTP body data.

NOTE: oapi-codegen _does_ support some custom type parsing, so we don't need to patch their parsing here. Date and Time are two hardcoded supported structs. Also, non-struct typedefs (like `type Address [21]byte`, which is our `staking.Address`) work fine.

func RuntimeFromURLMiddleware

func RuntimeFromURLMiddleware(baseURL string) func(next http.Handler) http.Handler

RuntimeFromURLMiddleware extracts the runtime from the URL and sets it in the request context. The runtime is expected to be the first part of the path after the `baseURL` (e.g. "/v1").

Types

type ErrStorageError

type ErrStorageError struct{ Err error }

func (ErrStorageError) Error

func (e ErrStorageError) Error() string