From 3ba4da76e44e61e78a04aadcc88853e2ddee5d13 Mon Sep 17 00:00:00 2001
From: Colin Okay <okay@toyful.space>
Date: Sat, 12 Feb 2022 14:33:25 -0600
Subject: comments to example

---
 example/lazybones-test.lisp | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/example/lazybones-test.lisp b/example/lazybones-test.lisp
index 3c04065..aca7a56 100644
--- a/example/lazybones-test.lisp
+++ b/example/lazybones-test.lisp
@@ -52,6 +52,8 @@
 ;; app whose name is the current package anme. DEFENDPOINT (without the *)
 ;; allows you to explictly specify the app where the endpoint is installed.
 
+;; The general syntax is: DEFENDPOINT* HTTP-METHOD ROUTE-TEMPLATE QUERY-PARAMETERS OPTIONS DOCSTRING BODY ...
+
 (defendpoint* :post "/login" () ()
   "Dummy login endpoint for returning a session cookie. Always returns
   the \"true\" and sends a set-cookie header, setting 'testappsession'
@@ -60,9 +62,11 @@
   (setf (lzb:response-cookie "testappsession") "coolsessionbro")
   (http-ok "true"))
 
+
+;; The next route defines a route variable WHO
 (defendpoint* :get "/hello/:who:" () ()
   "Echos back Hello WHO"
-  (http-ok (format nil "Hello ~a~%" who)))
+  (http-ok (format nil "Hello ~a~%" who)))  ; use the route variable here
 
 (defendpoint* :post "/hello/:who:" ()  (:auth t)  ; use the default authorizor for the app
   "Echo's back 'Hello WHO, I got your message BODY' where BODY is the post body."
@@ -82,6 +86,9 @@
   "A String"
   string)
 
+;; In the following, two query parameters are specififed. NAME is
+;; meant to be a string and AGE is an integer. If AGE is not an integer,
+;; a 500 error will be returned.  The syntax is (VAR PARSER)
 (defendpoint* :get "/search" ((name str) (age int)) ()
   "Echo the search parameters in a nice list."
   (http-ok (format nil "Name: ~a~%age: ~a~%" name age)))
@@ -96,7 +103,6 @@
 
 ;; Route variables can accept parsers / preformatters
 ;; these will parse a value and supply it to the argument of the handler.
-
 (defendpoint* :get "/random/:lo int:/:hi int:" () ()
   "Echo back a random number between lo and hi"
   (if (< lo hi) 
@@ -112,7 +118,9 @@
   ;; 500 response would be sent to the client.
   (list :name "Colin"  :occupation "Macrologist" :id (parse-integer id)))
 
-(defendpoint* :get "/person/:person person-by-id:" () (:content-type "application/json")
+
+(defendpoint* :get "/person/:person person-by-id:" () 
+  (:content-type "application/json")    ; override the app's default content type for HTTP responses
   "Returns a json representation of the person."
   (http-ok
    (jonathan:to-json person)))
-- 
cgit v1.2.3