donau

donau      REST API framework

a lightweight framework for defining and running REST APIs. It is based on express and automatically generates and serves an open api documentation.

features

• usable as standalone server or with existing express
• automatic Open API documentation generation/serving
• out-of-the-box auth handling
  • JWT authentication
  • Basic authentication
• simple and sleek developer experience
• type safe
• easy to use and extend
• integrated logging via logger

usage

check out the example project at /example

• minimal_example provides a rudimentary API serving just one endpoint
• auth_example provides a more complex API that defines nested endpoints and handles user authentication

simple example

an api can be defined and served just by:

defining the routes:

const routes: DonauRoute[] = [
  route("/hello/{greeting}", {
    description: `A simple hello world route`,
    parameters: [
      parameterPath("greeting", {
        description: "the greeting phrase",
      }),
    ],
    worker: (greeting) => {
      return greeting === "bye"
        ? err.badRequest("don't say bye")
        : { message: `${greeting}, my friend!` };
    },
  }),
];

and then configuring the server:

donauServerRun(1235 /* the port */, {
  info: {
    title: "basicAPI",
    version: "1.0.3",
    description: "an example API",
  },
  //cors: {origin: "*"},
  routes: routes,
});

that's it! the API is now running on localhost:1235/api. You can access the open api documentation at localhost:1235/docs.

If you want to disable the documentation, you can set docsPath: null.

authentication

you can of course provide your own authentication middleware to the server. but for convenience, the framework provides a prebuilt way to handle authentication. you can define a new JWTAuth object and pass it to the donauServerRun function:

const jwtAuth = new JWTAuth({
  secretKey: "mySecretKey",
  // remove onSignUp if you don't want to allow sign up
  onSignUp: async (username, passwordHash) => {...},
  // this provides a rich user object to your routes
  getUser: async (username) => {...},
  // load the password hash from your database
  getPasswordHash: async (username) => {...},
})


donauServerRun(1235, {
  info: {
    title: "basicAPI",
    version: "1.0.3",
    description: "an example API",
  },
  routes: yourRoutes,
  // this adds the auth middleware and routes to your API
  auth: jwtAuth,
});

you can then use the handlerAuthed function to define protected routes

server calls

donau also provides a simple client side API. this makes it possible to define functions both in the server and the client. This allows you to implement simple web applications without explicitly defining a REST API. The function calls are also type safe

• in a shared file, define your server call functions signatures

import { serverCall } from "donau/servercalls/shared";

export const serverCalls = {
  timesTwo: serverCall<{ n: number }, number>(),
  // pass {auth: true} to enable authentication
};

• in the client project, define the use-interface

import { useServerCalls } from "donau/servercalls/client";

const onServer = useServerCalls(serverCalls);

• in the server project, add the function definitions

import { handleServerCalls } from "donau/servercalls/server";

const scRoutes = handleServerCalls(serverCalls, {
  timesTwo: async ({ n }) => n * 2,
});

// then add those routes to your donau routes

now you're good to go. You can use the functions from the client by calling

const result = await onServer.timesTwo({ n: 2 });

Server Channels

If you wish to use WebSockets for real-time communication, you can utilize the Server Channels feature. This allows you to define channels that clients can subscribe to, enabling efficient data updates without the need for constant polling.

🚨 MAKE SURE TO INSTALL THE ws PACKAGE 🚨

contribution

you are most welcome to suggest improvements or contribute code via the github repository

I hope this package is useful to you,
Yours, Robin