OOPyness is an advantage. Object orientation allows one to:

• Recycle logic by defining protocol methods on mixin superclasses of endponit classes. Whole regions of a site or API can easly be extended or modified.
• You can use the reified endpoints to automatically for your API. See the function weekend:print-all-route-documentation.
• Similarly, you can automatically generate API client code for your langauge of choice.
• ENDPOINT itself can be sublcassed for special endpoint definition logic. E.g. ensuring a route prefix without having to type it each time can be acheived by specializing instantiate-instance on a subclass of ENDPOINT to alter the :route-parts.

All routes are defined by supplying route parts.

Each route part is a string and these strings are combined into a regular expression.

Match groups inside the regular expression are extracted and parsed according to the value of the :extractors slot.

If there are N match groups in a route, then there must be N extractors.

E.g

(defclass example ()
  ((foo-id
    :type integer
    :reader foo-id
    :initarg :foo-id)
   (bar-val
    :type string
    :reader bar-val
    :initarg :bar-val))
  (:metaclass weekend:endpoint)
  (:method . :get)
  (:route-parts "foo" "([0-9]+)" "bar" "(blah|nah)")
  (:extractors (:foo-id parse-integer) :bar-val))

In :route-parts there are four parts. Two of those parts are match groups: ([0-9]+) and (blah|nah). The :extractors slot has two extractor specs.

The route parts will be combined into a regular expression: "^/foo/([0-9]+)/bar/(blah|nah)$"

The first match group matches a string of digits. That string is parsed by parse-integer and then supplied to the :foo-id initarg.

The second match group matches either "blah" or "nah" and is passed as-is to the :bar-val initarg.

This class would handle the route GET /foo/322/bar/nah for example. It would not handle POST /foo/322/bar/nah nor GET /foo/xxx/bar/nah. In both latter caes a 404 would be returned to the client.

You might be asking yourself "why not just write the regex as a string?" Well that's a good question. You can actually do that (dig into the endpoint metaclass yourself to see how), but the reason I prefer :route-parts is that it allows for defining reusable regex patterns and storing them in global parameters. See examples/dice-roller.lisp.

Here we modify the above example by only passing one argument in the route, leaving the other to be a query parameter.

(defclass example2 ()
  ((foo-id
    :type integer
    :reader foo-id
    :initarg :foo-id)
   (bar-val
    :type string
    :reader bar-val
    :initarg :bar-val
    :initform (weekend:slot-required 'bar-val 'example2))
  (:metaclass weekend:endpoint)
  (:method . :get)
  (:route-parts "foo" "([0-9]+)" "bar")
  (:extractors (:foo-id parse-integer)))

This would handle routes like GET /foo/323/bar?bar-val=moo

If bar-val had not been supplied in the query parameters, the slot-required error would be signalled and the client would receive a 400 HTTP response code.

Though not necessary, users may wish to avail themselves of a small endpoint-defining language called DEFENDPOINT.

See the defendpoint examples.

DEFENDPOINT was made using argot, a grammar-driven approach for defining DSL macros. As such, a docstring describing the grammar is generated and attached to the DEFENDPOINT macro - I suggest you consult it.

(print (documentation 'weekend:defendpoint 'function))