<buttonid="themeToggleButton"class="jsonly">Change Color Theme</button>
<hr>
</header>
<article>
<header>
<h1>Creating an API with Handy-Httpd</h1>
<p>
<em>Written on <timedatetime="2023-09-26">September 26<sup>th</sup>, 2023</time>, by Andrew Lalis.</em>
</p>
</header>
<section>
<h2>Introduction</h2>
<p>
When I started programming in the D language, I was coming fresh from the world of Java and Spring, where setting up a new web API for a project was pretty much as simple as creating a new method annotated with <code>@GetMapping</code>. In the D world, the closest thing to an all-encompassing web framework is <ahref="https://vibed.org/"target="_blank">Vibe.d</a>, which is quite convoluted (from a beginner's perspective), and is heavily focused on its own ecosystem and async implementations. That gives it a sort of "walled-garden" feel. There were other, smaller HTTP web server libraries, but none were well documented. So in the end, I set out to build my own HTTP server, which then evolved into more of an HTTP web framework. That's <ahref="https://github.com/andrewlalis/handy-httpd">Handy-Httpd</a>.
</p>
<p>
Handy-Httpd was built on the concept of an <code>HttpRequestHandler</code>, a single unit that takes an HTTP request and does stuff with it.
</p>
<figure>
<pre><codeclass="language-d">
class ExampleHandler : HttpRequestHandler {
void handle(ref HttpRequestContext ctx) {
ctx.response.writeBodyString("Hello world!");
}
}
</code></pre>
<figcaption>Here's an example of an <code>HttpRequestHandler</code> that just responds with <em>"Hello world!"</em> to any request.</figcaption>
</figure>
<p>
With this request handler, and the <ahref="https://en.wikipedia.org/wiki/Object_composition">principle of composition</a>, we can build up a complete web framework from a few well-purposed handlers.
</p>
</section>
<section>
<h2>Setting Up</h2>
<p>
As with any web server, there's some startup and configuration that needs to be done to get everything working, so we'll get that out of the way first.
</p>
<p>
We need to create a new D project, and add <code>handy-httpd</code> as a dependency. Do so with the <code>dub</code> CLI tool, or however you prefer to create D projects. Then we'll set up the basic HTTP server in our project's main file.
PathDelegatingHandler pathHandler = new PathDelegatingHandler();
// TODO: Add mappings to pathHandler
HttpServer server = new HttpServer(pathHandler, config);
server.start();
}
</code></pre>
</figure>
<p>The typical boilerplate consists of three main things:</p>
<ol>
<li>Configuration</li>
<li>Building our request handler</li>
<li>Starting the server</li>
</ol>
<p>
For illustrations' sake, I've configured this server to use 3 workers in its pool for handling requests. You might need more depending on your traffic. I've also created a new <code>PathDelegatingHandler</code> which will serve as the basis for the API's set of endpoints. Check out the <ahref="https://andrewlalis.github.io/handy-httpd/guide/handlers/path-delegating-handler.html">documentation on this handler</a> for a detailed explanation of what it can do; in short, we can register new API endpoints to it.
</p>
</section>
<section>
<h2>Adding an Endpoint</h2>
<p>
Now that our server is set up, all we need to do is define some endpoints for users to interact with. This is as simple as creating an <code>HttpRequestHandler</code> and registering it with our <code>pathHandler</code> that we defined on line 7.
</p>
<p>
To keep things simple to start, we'll add a <em>status</em> endpoint that just returns the string <em>"online"</em>. For something this basic, there's no need to create a whole new class; instead, we'll just define a function.
</p>
<figure>
<pre><codeclass="language-d">
void handleStatus(ref HttpRequestContext ctx) {
ctx.response.writeBodyString("online");
}
</code></pre>
</figure>
<p>
And then, we'll register it with our path handler so that GET requests to <code>/status</code> will be directed to the <code>handleStatus</code> function.
Done! We can now run our project and navigate to <ahref="http://localhost:8080/status">localhost:8080/status</a>, and we should see the text <em>"online"</em>. It's that simple.
</p>
</section>
<section>
<h2>Posting Data to Our API</h2>
<p>
A GET endpoint is easy enough, but making an endpoint that accepts the user's data isn't too hard either.
You're not limited to only JSON though; users can upload URL-encoded data, or XML, or literally anything else. It's just that D's standard library provides a JSON implementation, so Handy-Httpd gives you some help with it.
</p>
<p>
Under the hood, Handy-Httpd uses the <ahref="https://github.com/andrewlalis/streams">streams</a> library for the underlying data transfer, so if you're looking for a completely custom solution, you'll need to read from <code>ctx.request.inputStream</code>, which is a <code>InputStream!ubyte</code>. Also note that each request has a pre-allocated <code>receiveBuffer</code> that you can use instead of creating your own separate buffer.
</p>
</section>
<section>
<h2>Adding Middleware with Filters</h2>
<p>
One of the buzz words these days in web programming is <em>"middleware"</em>, which is just a fancy term for anything that sits between two systems and performs some limited set of functions on the data that is passed between the systems.
</p>
<p>
In Handy-Httpd, we've provided a convenient method of adding middleware to the HTTP request handling flow with the <code>HttpRequestFilter</code>, <code>FilterChain</code>, and the <code>FilteredRequestHandler</code>.
<figcaption>An illustration of how an HTTP request is processed by a FilteredRequestHandler: first it goes through all pre-request filters, then the underlying handler, and finally any post-request filters.</figcaption>
</figure>
<p>
Suppose we want to authenticate requests to certain endpoints. That's a pretty straightforward task that many web frameworks deal with. In Handy-Httpd, you'd create a filter that reads a JWT token from the request's header, decodes it, and adds user info to the request context's <code>metadata</code> property.
Then to actually use your newly-created <code>TokenFilter</code> to safeguard your endpoint, you'd use the <code>FilteredRequestHandler</code> to wrap your endpoint and set the TokenFilter as one of the pre-request filters.
</p>
<figure>
<pre><codeclass="language-d">
FilteredRequestHandler frh = new FilteredRequestHandler(
mySuperSecretEndpoint,
[new TokenFilter()]
);
</code></pre>
</figure>
<p>
That's all there is to it! No runtime magic, just composing a handler that does exactly what you tell it to.
</p>
</section>
<section>
<h2>Additional Remarks</h2>
<p>
While I've done my best (which admittedly isn't that good) to keep Handy-Httpd lightweight and performant, that really isn't the number 1 goal. My goal was always to build a simple HTTP server with some nice-to-have conveniences that don't require months of diligent study to use effectively. I wanted something with sufficient documentation so that Handy-Httpd can be a D programmer's first introduction to HTTP servers.
</p>
<p>
We're now on version <em>7.10.4</em> as of writing this article, and I feel like Handy-Httpd is in a place where I can comfortably say that it's reached those goals. Thanks for reading all the way through, and if you do try out Handy-Httpd, please do let me know what you think!
