Scaffolding API projects easily with oak-routing-ctrl
Tags: deno, typescript, api, tooling
Published: 2024-06-20 22:06:19

Greetings to Deno / TypeScript / JavaScript community!

Today I'd love to introduce a DevTool: [oak-routing-ctrl](https://jsr.io/@dklab/oak-routing-ctrl)

Now if you read the link above & still are unsure what this tool does, then I hope this article may help 😀

Let's say you:

1. wanna build a microservice that provides a set of API to your consumers
2. chose the [oak framework](oakserver.org) as your HTTP middleware library
3. do not want to write repeated routing code for all your API endpoints

Then `oak-routing-ctrl` might be worth a try.

Here is what's in the box:

## 1. TypeScript Decorators

First we have a set of TypeScript Decorators (conforming to [TC39 proposal](https://github.com/tc39/proposal-decorators)) that makes it straightforward to declare API endpoints & assign it to a handler function in a few lines of code:
```ts
// MyController.ts

import { Controller, Get } from "@dklab/oak-routing-ctrl@0.7.4";

@Controller()
export class MyController {
  @Get()
  doSomething() {
    return "hello, dev.to";
  }
}
```

## 2. An initiation helper function

Now to actually spin up an HTTP server, we'll need to initiate the server instance e.g. with the middleware [oak](https://jsr.io/@oak/oak), and glue it up with the API route handler function we wrote above. Of course it can be in the same file, or a different file, up to your flavour. Here we use a different file:
```ts
// main.ts

import { Application } from "@oak/oak@16.1.0";
import { useOakServer } from "@dklab/oak-routing-ctrl@0.7.4";
import { MyController } from "./MyController.ts";

const app = new Application();
useOakServer(app, [MyController]);
await app.listen({ port: 1993 });
```

The example code so far assumes we're on `Deno` runtime. But heads up: both `oak` and `oak-routing-ctrl` [fully support other runtimes](https://github.com/Thesephi/oak-routing-ctrl?tab=readme-ov-file#other-runtimes) (Bun, Cloudflare Workers, and Node.js).

With Deno assumed, let's start our server up:
```bash
deno run --allow-env --allow-net main.ts
```

And send a test cURL:
```bash
curl localhost:1993
# prints: hello, dev.to
```

That was the most simple form of it. More complex examples are available in the [README](https://github.com/Thesephi/oak-routing-ctrl?tab=readme-ov-file#example-retrieving-path-parameters).

## Looking forward...
Up to this point, you may wonder what's so special about this library. I, as the author, am of course biased, but if you must know: nope, it's indeed "_just another DevTool_". I'm not taking pride in its superb performance or any underlying rocket science, I do appreciate the level of care and seriousness I myself put in while developing it. Before it reaches the "relatively stable" version of 0.7.4 (at which time I write this blog post), it went through a valley of alpha releases:

![screenshot of the oak-routing-ctrl library on its JavaScript Registry page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t3n8i3cvynb9y17en4yr.png)

I don't intend to put much more logic in it from this point on. After using it on production for a while, I'll bump it to 1.0.0. It's released under MIT & anyone can [contribute](https://github.com/Thesephi/oak-routing-ctrl/blob/main/CONTRIBUTING.md) or even fork their own development directions.

What I commit to is the **continuous maintenance** of this library. It is used on production for my own and my employer's web-scale products, thereby giving me "unfair incentives" to keep it sane & performant.

If you use it for your work, I would really love to hear your thoughts and suggestions, i.e. what you like, what you don't like. A GitHub <a class="github-button" href="https://github.com/Thesephi/oak-routing-ctrl" data-color-scheme="no-preference: light; light: light; dark: dark;" data-icon="octicon-star" data-size="large" aria-label="Star Thesephi/oak-routing-ctrl on GitHub">Star</a>, or a constructive feedback issue, to me is equally valuable.

If I still have you on this line, it means my English skill is not any more rusty than my coding skill ;) and it means the world to me (😀). If you feel I missed something, or said something contrary to your knowledge, please feel free to place your questions in the comment section down below. Discussing tech topics is the best way for everyone to learn!

Thank you for your time on this blog post. Have a blast in what you're doing, wherever you are 🍻