Build strong and efficient REST web services.
Why write code when you have an OpenAPI 3.1 definition?
Whook eats your documentation and provides you with a performant router that takes care of running the right code for the right operation.
By using the OpenAPI standard and the dependency injection pattern, Whook provides a convenient, highly modular and easily testable back end framework.
To start a new Whook project:
# Initialize the project
npm init @whook;
cd my_project_name;
# Check install with a dry run of the server
npm run dev -- __inject httpServer,process,dryRun
# Run tests
npm t
# Start developing
npm run watch
# Build the project
npm run build
# Start the compiled project
npm start
# Start the built project
node builds/local/server/start.js
# Create a new handler/service/provider
npm run whook -- create- robust: types, functional programming
- highly modular, extendable and reusable
- fully integrated and production ready
- can be deployed anywhere (serverless, docker, microservices): enter the anylith era
- easy to test: TDD, E2E tests made easy
- feature complete for most API use cases
- ease your work but embrace projects complexity
A tutorial is still to be written, expect it to come very soon. The above quickstart command is a good starting point.
That said you can check the following "How to" PRs:
Also, the packages/ folder contains a lot of easy to setup
modules with well detailed readmes and setup instructions.
Finally, search for Whook's package easily with the NPM's Whook tag. Also the Knifecycle tag can be useful to find projects using the same dependency injection framework.
If you have any question or issue using Whook, post your help request to stack overflow with the Whook tag. Questions with this tag will be regularly checked by Whook's authors.
Finally, if you encounter any bug (unexpected error, feature requests, OpenAPI specification violation), please fill an issue!
Check this deck for a complete introduction to Whook's principles!
This projects aims to make creating well documented and highly customizable REST APIs a breeze. It is the final outcome of my experience building REST APIs with NodeJS.
By relying on the OpenAPI schemas to declare a new endpoint, this project forces documentation before code. It also is highly customizable since based on the dependency injection with inversion of control pattern allowing you to override or wrap its main constituents.
The Whook route handling flow is very simple.
First, we have a HTTPServer that handles requests and serves responses (the
httpServer service).
Then, the httpTransaction transform the NodeJS requests into raw serializable
ones (raw objects with no methods nor internal states, useful for testing).
Then the router (httpRouter) deal with that request to test which handler
needs to be run by comparing the method/path couple with the OpenAPI operations
declarations.
Once found, it simply runs the right handler with the OpenAPI parameters value filled from the serializable request. The handler simply have to return a serializable response object in turn.
If any error occurs within this process, than the errorHandler is responsible
for providing the now lacking response object based on the error it catches.
And that's it, you have your REST API. We have no middleware concept here. Instead, every handler is a simple function taking paramters and returning a response. It makes those functions very easily composable (in a functional programming sense).
You may add global wrappers to change every handlers input/output on the fly or add a local wrapper specifically to one of a few handlers.
Whook work by adding ingredients to you API:
- configuration: Whook look ups for
config/{NODE_ENV}/config.jsfiles. It creates constants you can inject in your handlers and services. - API: It defines the various endpoint of your API and how to map these to handlers thanks to the well known OpenAPI format (formerly Swagger),
- handlers: the code that implement the API endpoints,
- services: various services that deal with side effects,
- wrappers: higher order functions you can apply to handlers (CORS, authentication...).
You can see a lot of those concepts implemented in the Whook example folder.
Whook's DI system relies on the Knifecyle module. It is great for adding or easily override/wrap a lot of its core component and brings instrumentation and testability to your code bases.
Contributors are very welcome to help pushing Whook forward!
Clone this project's repository and run:
npm i
npm run build
npm run metapak
npm tThe repository is based on LernaJS that allows to host several NPM packages in a single repository. That said, to keep it simple it only proxies the packages commands.
Install those VSCode extensions to get a smooth developer experience.
For committing run:
npm run czNODE_ENV=cli npm run lerna -- publish