preludes / http-api.lisp

http-api

Effect HttpApi. APIs, groups, endpoints, and handlers that emit a typed Effect 4 HttpApi and builder.

Spike5 forms · 5 types · 106 linesPrelude HTTP API spike →Source

Bootstrap it with compiler.lisp, separately from the ontology's older api form.

From the source

Purpose: Effect HttpApi declarations with quasiquoted TypeScript emit hooks. Requires: compiler.lisp; bootstrap separately from the ontology's older api form. Used by: The optional TypeScript HTTP linker and derived typed builder DSL.

Forms 5

Keywords this prelude adds. Each is a form descriptor: its slots, their types, and the IR it produces.

(endpoint name method path {:keys [params payload success errors]})http-api.lisp:18

An HTTP endpoint with checked request and response schemas.

Slot	Type
name	(Declares EndpointDecl)
method	(Union :get :post :put :patch :delete)
path	String
params	(Option Type)
payload	(Option Type)
success	Type
errors	(Option (List Type))

Produces HttpEndpointIR · has a TypeScript :emit hook

Example

(: health (-> {} (Effect String)))
(define health [request] "ok")
(api Health
  (group system (endpoint health :get "/health" :success String)))
(handle Health system (handler health health))

(group name endpoint ...)http-api.lisp:43

Groups checked endpoint declarations into an Effect HttpApiGroup and emits its chained add calls.

Slot	Type
name	(Declares GroupDecl)
endpoint	(List endpoint)

Produces HttpGroupIR · has a TypeScript :emit hook

Example

(: health (-> {} (Effect String)))
(define health [request] "ok")
(api Health
  (group system (endpoint health :get "/health" :success String)))
(handle Health system (handler health health))

(api name group ...)http-api.lisp:59

Groups checked HTTP groups into an Effect HttpApi and emits its chained add calls.

Slot	Type
name	(Declares ApiDecl)
group	(List group)

Produces HttpApiIR · has a TypeScript :emit hook

Example

(: health (-> {} (Effect String)))
(define health [request] "ok")
(api Health
  (group system (endpoint health :get "/health" :success String)))
(handle Health system (handler health health))

(handler endpoint operation)http-api.lisp:77

Links an endpoint name to an ordinary operation. The HTTP linker checks the operation against request, success, and error schemas.

Slot	Type
endpoint	Symbol
operation	Symbol

Produces HttpHandlerIR · has a TypeScript :emit hook

Example

(: health (-> {} (Effect String)))
(define health [request] "ok")
(api Health
  (group system (endpoint health :get "/health" :success String)))
(handle Health system (handler health health))

(handle api group handler ...)http-api.lisp:92

Registers a group's handlers against a declared Effect HttpApi through HttpApiBuilder.group.

Slot	Type
api	(Refers ApiDecl)
group	Symbol
handler	(List handler)

Produces HttpHandleIR · has a TypeScript :emit hook

Example

(: health (-> {} (Effect String)))
(define health [request] "ok")
(api Health
  (group system (endpoint health :get "/health" :success String)))
(handle Health system (handler health health))

Types 5

Payload contracts and IR shapes, shown as authored.

HttpEndpointIRhttp-api.lisp:8

(type HttpEndpointIR
  {:kind "HttpEndpoint" :name Symbol :method Keyword :path String
   :params (Option Type) :payload (Option Type) :success Type
   :errors (Option (List Type))})

HttpGroupIRhttp-api.lisp:12

(type HttpGroupIR {:kind "HttpGroup" :name Symbol :endpoints (List HttpEndpointIR)})

HttpApiIRhttp-api.lisp:13

(type HttpApiIR {:kind "HttpApi" :name Symbol :groups (List HttpGroupIR)})

HttpHandlerIRhttp-api.lisp:14

(type HttpHandlerIR {:kind "HttpHandler" :endpoint Symbol :operation Symbol})

HttpHandleIRhttp-api.lisp:15

(type HttpHandleIR
  {:kind "HttpHandle" :api Symbol :group Symbol :handlers (List HttpHandlerIR)})