1 What

lazybones is a small HTTP routing framework.

Features include:

  • Different server backends. (At the moment only Hunchentoot is supported)
  • Modular and "installable" applications.
  • Handy macros for provisioning apps and defining endpoints.
  • In particular, endpoint routes may contain variables and include parsers for variables and for query parameters
  • customizable errors.
  • Livecoding supported for your endpoint handlers and application configurations.
  • Automatic documentation generation for lazybones:app instances.

Although lazybones can be used to develop and serve page-oriented web sites, it has been written to help me develop "self documenting" HTTP APIs.

1.1 Main Components

The main components in lazybones are the two classes: lazybones:app and lazybones:endpoint.

Endpoints are objects that represent everything required to handle an HTTP request. Endpoints are collected into groups called apps.

Apps, in addition to being collections of endpoints, are the main unit of development for larger lazybones projects. Apps can be installed to running servers on the fly as whole units. If desired, they can also be uninstalled. Apps are meant to be devolped in a one-app-per-package manner. That is, although you can create and work with multiple apps in a single Common Lisp package, lazybones encourages you to limit yourself to one per package.

See the example below for more.

1.2 A Hello World Example

(asdf:load-system "lazybones-hunchentoot")

(defpackage #:hello-lazybones
  (:use #:cl)
  (:local-nicknames (#:lzb #:lazybones))
  (:import-from #:lazybones #:defendpoint* #:http-ok))

(in-package :hello-lazybones)

(defendpoint* :get "/hello/:name:" () ()
  "Responds with a greeting to NAME" 
  (format nil "Welcome to Lazybones, ~a" name))

(defvar *my-server* (lzb:create-server))
(lzb:install-app *my-server* (lzb:app))
(lzb:start-server *my-server*)

Go ahead and test this sever out with curl:

$ curl -v http://localhost:8888/hello/colin
Connected to localhost ( port 8888 (#0)
> GET /hello/colin HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/7.74.0
> Accept: */*
Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Length: 27
< Date: Wed, 09 Feb 2022 12:26:01 GMT
< Server: Hunchentoot 1.3.0
< Content-Type: text/html; charset=utf-8
Connection #0 to host localhost left intact
Welcome to Lazybones, colin

Check the example directory in this repository for a more elaborate example.

1.3 Documentation Generation

You can generate Markdown documentation for an instance of layzbones:app using lazybones:generate-app-documentation. For an example API and example documentation, see the example directory in this repository.

1.4 Backends

WARNING Users can mostly ignore thissection. The API for alternate backends is in flux.

To implement a new backend for lazybones, consult the lazybones.backend package. Define a new system and a new package that uses the lazybones.backend package. Implement functions for each symbol. Consult the lazybones-hunchentoot system for an example backend.

Created: 2022-11-07 Mon 19:46