Introducing Whook
Extensible APIs done well

about:nfroidure

Web Platform Architect
 

Building softwares for Lille's innovative startups since JavaScript is a hot topic.

 

Almost passed the Rust compiler checks once.

 

Blog & Tweet randomly

Design choices

Open API based
Bring OAS3 definitions and get a router!

  • A very wide used standard
  • Learn a standard instead of a framework
  • Enforces documentation (no doc, no route)

No OOP
FP without hysteria

  • requests / responses are plain
    serializable objects
  • handlers / services are just async
    functions
  • middlewares are just higher order
    functions (called wrappers)

Dependency Injection
at its core with Knifecycle

  • Highly customizable
  • Easily testable (E2E, unit...)
  • Configurable and manageable
  • Optimized
  • Lightweight (build only necessary code)

TypeScript

  • Less bugs
  • Better developer experience
  • But you may still use raw JS

Configuration
over code

  • Less breaking compatibility
  • Auto-completed configuration
  • Plugins for a lot of common use cases
  • Still possible to override the code

KISS

  • introduce only a few specific concepts
  • flavor for extendable code over
    embrassing every use cases
  • WET over DRY

Enterprise focused

  • always favor reliability over ease of use
    (that said, provide both when possible)
  • built for easy teams scaling over easy toy
    projects setup

Getting started

> npm init @whook

Dev commands

  • `npm run dev`: run the backend for
     dev (typically for frontend devs)
  • `npm run watch`: work on the backend
    (generates Open API types on the fly)
  • `npm run whook-repl`: inject and use
    services on the fly

Key concepts

Services

  • Initialize a reusable portion of code
  • Usually, one that maintain states (IOs, FS, DB..)
  • Can depend on other services
  • Create new ones with:
    > npx whook create --type service
  • find them in `src/services`

Providers

Like services but with extras behaviors

  • Can declare a shutdown hook so that
    when the server is shut down, the service
    cleans up its states (close DB connections)
  • Can declare an error promise to shut down
    the server if anything goes wrong
  • Create new ones with:
    > npx whook create --type provider
  • find them in `src/services`

Handlers

  • Implementation of an endpoint
  • Often also contains its definition
  • Can depend on other services
  • Can also reuse other handlers's code
    (they are just a special kind of service
    after all)
  • Easily override an handler by proxying it
  • Create new ones with:
    > npx whook create --type handler
  • find them in `src/handlers`

Wrappers

  • Wrap handlers to enrich their behavior
  • Take an handler in parameter and
    output a new one
  • Like Express middlewares but done
    with higher order function
  • Useful for CORS, auth and others...
  • Can be set globally thanks to the
    WRAPPERS service
  • find them in `src/wrappers`

API

  • A service that gather each handlers
    definitions
  • Allow to make transformations
    on the overall API
  • Mostly automated by the
    API_DEFINITIONS service
  • find it at `src/services/API.ts`

Configurations

Commands

  • Meant to tie CLI tools with the backend
    (sample command)
  • Provide all injectable services
  • All commands can be listed with:
    > npm run whook -- ls
  • To create a new command:
    > npm run whook -- create --type command
  • find them in `src/commands`

Main (index.js)

Allows to declare:

  • the process environnement
  • the server run function
  • thought to be extendable

Avanced usage

Autoloader

Plugins

  • One can create plugins to provide
    extra services / handlers / commands
    out of the box by simply declaring it
  • Default plugins can be completly released
    for a full customized experience

Service name map

  • replace services per others for a given env
  • replace services per others easily
  • avoid extra costs by using mocked services
    in your preprod / uat envs

AWS Lambda

@whook/aws-lambda

  • Build lightweigtht Lambda functions
    but still avoid being vendor locked
  • Easily adapt your lambdas for any
    other cloud provider
  • sample use of the module

GraphQL

@whook/graphql

Debugging

You never know!

Output debug infos

- to output Whook debug infos:

DEBUG=whook npm run dev


- to debug the router:

DEBUG=siso npm run dev


- to debug DI issues:

DEBUG=knifecycle npm run dev

Using the debugger

- for the Whook server:

npm run debug


- for commands:

npm run whook-dev -- ls

Ask for help!

  • each error has a single code
  • direct link to Stack Overflow :
    find answers easily or create yours

Thanks! Questions?

Introducing Whook

By Nicolas FROIDURE

Introducing Whook

Building extensible APIs can be hard to achieve, Whook brings easy to start with but yet extensible and customizable way to do it well.

  • 1,681