A.19 SOFTWARE-EVOLUTION-LIBRARY/REST/DEFINE-COMMAND-ENDPOINT

Macro: define-endpoint-route [sel/rest/define-command-endpoint] route-name func required-args &optional command-line-args environment status-fn

Macro to define routes to run the function and retrieve results.

The ‘define-endpoint-route‘ macro sets up endpoint routes via ‘DEFROUTE‘ to start asynchronous jobs remotely, mirroring the command definitions from ‘define-command‘. The arguments are:

• route-name - The name to use for the REST route.
• func - The function to invoke on given arguments
• required-args - The named arguments to the function with associated types, which will be used to decode the post JSON (e.g., ‘((x integer) (y string))‘).
• command-line-args (optional) - Additional, optional arguments defined as per command-line.lisp.
• environment (optional) - Variables to let-bind before starting the function (such as globals we should dynamically bind). These will be initialized to nil before each ‘func‘ task is created.
• status-fn (optional) - A function to run to retrieve the status of the endpoint. It takes the current session and job name as input. If none is specified, it defaults to ’sel/rest/async-jobs::lookup-session-job-status.

For example, the following invocation of ‘define-endpoint-route‘ will set up an endpoint that adds five to numbers:

(define-endpoint-route addfive (lambda (value) (+ value 5)) ((value integer)))

An appropriate REST invocation for this endpoint might look like:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" http://127.0.0.1:9003/addfive?cid='client-1001' -d '{"value" : 5}'

In addition, you can directly name endpoint functions, e.g.:

(define-endpoint-route fact #'alexandria::factorial ((value integer)))

In this case, the function must be in scope wherever this macro is envoed.