blob: ee2b08ad6c0c2c8be183e31bee07cbcb31b002fd (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
|
* WEEKEND: another HTTP endpoint building library
With ~WEEKEND~, endpoints are classes defined with the metaclass
~endpoint~.
The ~endpoint~ metaclass provides a number of class-level slots which
specify the HTTP method and the route that the class is meant to
handle.
Compiling the endpoint class automatically builds and registers a
hunchentoot handler. Recompiling the class removes the old handler and
builds a new one.
Instance slots of an ~endpoint~ class hold data necessary to process
the request. If a slot is defined with an ~:initarg~, then that slot's
value is meant to be supplied by the HTTP request, be through embedded
"route variables", query parameters, or fields in a structured request
body.
Any slot defined without an ~:initarg~ is meant to have its
value supplied by some stage in the handler protocol.
The handler protocol is used to control the handling of requests. All
endpoint classes are required to specialize the ~weekend:handle~
method. Optionally they may also specialize the ~weekend:authenticate~
and ~weekend:authorize~ methods.
Before ~handle~ is called, ~authorize~ is called, and before
~authorize~ is called, ~authenticate~ is called. If either
~authenticate~ or ~authorize~ return ~NIL~, then the appropriate HTTP
error is returned to the client. Otherwise ~handle~ is assumed to have
all it needs to produce the content to be returned to the requesting
client.
** Examples
See [[https://cicadas.surf/cgit/colin/weekend.git/tree/examples][examples]] for a few examples.
** Advantages of the Approach
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.
- ~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~.
- You can use the reified endpoints to automatically generate nice
documentation. (Less than nice documentation is already provided via
the function ~weekend:print-all-route-documentation~.)
- Similarly, you can automatically generate API client code for your
langauge of choice.
|
