This type defines an API specification. It's a map of endpoint names to endpoint specifications. While the names
are arbitrary, it's generally easiest to use something like "GET /users/:id" as the name, as that makes it very
obvious what endpoint we're dealing with and also very easy to find an endpoint within a given spec.
Important things to know about an API spec:
You must provide a method, endpoint, and validate, authorize, and handle functions for each endpoint. The rest are
optional. If you don't feel the need to validate inputs or authorize requests, you can just provide pass-through
functions.
The validate function is intended to take in the request's URL params, query params, and body, along with the
request's auth information and return a specifically-typed "params" object which may be anything you'd like. This
is to address annoyance of your handlers having to figure out where to get the params they need to do their work.
Your handler, then, simply works with the params output from this function and can forget about the details of
where those params come from.
The authorize function can technically be any logic, but is pre-configured to work with the authorize function
exported from this library. See the main readme for more information.
The handle function is your primary handler and will often be a thin wrapper over a library function representing
a piece of your business logic. It may do some minor transformations of input params (or not) and will then return
a standardized response object that this system recognizes.
Finally, if you need additional functionality for any reason (for example, to insert headers into the response or
further manipulate input params or something), you can pass a variety of hooks.
A type defining the inputs (params) and outputs (response) of each endpoint. Note that
response is intended to be the type of the data returned by this endpoint. This API system will wrap that data
in a more fully-featured response object (see Api.Response
for more on that).
This type defines an API specification. It's a map of endpoint names to endpoint specifications. While the names are arbitrary, it's generally easiest to use something like "GET /users/:id" as the name, as that makes it very obvious what endpoint we're dealing with and also very easy to find an endpoint within a given spec.
Important things to know about an API spec:
validate
function is intended to take in the request's URL params, query params, and body, along with the request's auth information and return a specifically-typed "params" object which may be anything you'd like. This is to address annoyance of your handlers having to figure out where to get the params they need to do their work. Your handler, then, simply works with the params output from this function and can forget about the details of where those params come from.authorize
function can technically be any logic, but is pre-configured to work with theauthorize
function exported from this library. See the main readme for more information.handle
function is your primary handler and will often be a thin wrapper over a library function representing a piece of your business logic. It may do some minor transformations of input params (or not) and will then return a standardized response object that this system recognizes.