clean up some lint issues
[squeep-api-dingus] / README.md
1 # Another In-House API Server Frameworklet
2
3 I just wanted a basic little API server for toy projects, without having to park a container-ship of modules under it.
4
5 This is in no way intended to replace any mature, full-featured framework. It is spartan in some aspects, brings some unexpected baggage in others, makes some questionable design decisions, has the occasional opinion, and is likely somewhat idiosyncratic from an outside perspective.
6
7 This was also created as a means to gain a better understanding of the existing web framework ecosystem by fussing with all the involved fiddly bits, a priori, from the bottom up.
8
9 The primary design goals are:
10 - self-contained: as few external dependencies as feasible
11 - not-infinitely-extensible: only does the things it needs to do as dictated by the projects it is used in
12 - learning from mistakes made along the way
13
14 ## Getting Started
15
16 Construct it with a console-level-compatible logger object capable of doing something meaningful with calls like `logger[level](scopeString, messageString, dataObject)`.
17
18 Within the server request handler:
19 - `dispatch(req, res)` makes things go.
20
21 Within the application implementation:
22 - `on(method, urlPath, handler)` declares a thing to do when a request matches.
23 - `preHandler(req, res, ctx)` can be overridden to do something to every request before it is handled.
24
25 Handled content types can be extended by overriding:
26 - `parseBody(contentType, ctx)` for incoming types.
27 - `renderError(contentType, err)` for outgoing types.
28
29 Within your handlers:
30 - `setResponseType(responseTypes, req, res, ctx)` can be called to negotiate content types.
31 - `async ingestBody(req, res, ctx)` will parse request body data.
32 - throw an `Error.ResponseError` with an `Enum.ErrorResponse` for a simple status code with optional details, when something goes awry.
33
34 Parameters and metadata are set in each request context.