The defrest Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The defrest Reference Manual

This is the defrest Reference Manual, version 1, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:42:07 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

defrest

Export functions via REST Webservices with hunchentoot in an easy way.

defrest provides a very easy way to expose functions via REST interfaces with the hunchentoot webserver.

Exposing a REST Interface is as simple as:

(defrest "/hello" :GET ()
	 "Hello World!")

or more sophisticated with embedded Path-Parameters and json response

(defrest "/length/{str:.+}" :GET (str)
	(with-output-to-string (*standard-output*) 
	 (cl-json:encode-json (list (cons 'name  str) (cons 'length (length str))))))

This will build a dispatcher which will listen to urls with the regexp "/length/.+" , bind the (.+) to the str variable , runs the body with it and sends the result.

Path-Parameters are encoded as Template blocks {VARNAME:REGEXP}. defrest will do all the parsing and matching for you. Additionally the hunchentoot handler environment is available, so you can access hunchentoot:*request* and so on.

defrest also supports query parameters:

(defrest "/songs/{album-id:[0-9]+}" :GET (album-id :query offset limit)
        (get-songs album-id offset limit))

Query-Parameters are separated from the path-parameters by the keyword :query. They are not used by the route matching algorithm. Query-Parameters can be declared as simple variable names (where the names represents the names of the query parameters of the current request) or as lambda-lists with the following format:

query-param -- (binding &key (mandatory nil) (pattern nil) (param nil) (default nil))

Query-Parameter examples:

(defrest "/songs/{album-id:[0-9]+}" :GET (album-id :query (offset :default "0") limit)
        (get-songs album-id offset limit))
(defrest "/songs/{album-id:[0-9]+}" :GET (album-id :query (offset :default "0") (limit :mandatory t))
        (get-songs album-id offset limit))
(defrest "/songs/{album-id:[0-9]+}" :GET (album-id :query (offset :default "0") 
    (limit :mandatory t :pattern "[0-9]+"))
        (get-songs album-id offset limit))
(defrest "/songs/{album-id:[0-9]+}" :GET (album-id :query (offset :default "0") 
    (count :mandatory t :param "limit"))
        (get-songs album-id offset count))

The defrest body should return a string. All other values are format~a'ed to it.

The Method can be replaced with :PUT :POST :DELETE etcpp

You can add defined webservices to hunchentoot in two different ways:

  1. Let defrest take care of it:

    just add (create-rest-table-dispatcher) to the hunchentoot dispatcher. Like this:

    (push (create-rest-table-dispatcher) hunchentoot:*dispatch-table*)
    

    and you are done

  2. Add them by yourself:

    defrest returns a dispatcher which you can chain into hunchentoot. However, you will loose the ability to defrest on toplevel, that way...

    (setq hunchentoot:*dispatch-table*
        (list (defrest "/sqrt/{number:[0-9]+}" :GET (number) (sqrt (parse-integer number)))))
    
    

Tests

The Test suite can be run automatically by asdf:

(asdf:oos 'asdf:test-op 'defrest)

See minimal-example.lisp for exactly what its called

defrest was called defajax

Copyright (C) 2013 by Mathias Menzel-Nielsen


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 defrest

Author

Mathias Menzel-Nielsen <(reverse "ed.tfosztam@eztam")>

License

BSD

Description

defrest: expose functions as REST webservices for ajax or other stuff

Version

1

Dependencies
Source

defrest.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 defrest.asd

Location

defrest.asd

Systems

defrest (system)

Packages

defrest-system


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 defrest/defrest.lisp

Parent

defrest (system)

Location

defrest.lisp

Packages

defrest

Exported Definitions
Internal Definitions

Previous: , Up: Files   [Contents][Index]

3.2 Static


Previous: , Up: Static files   [Contents][Index]

3.2.1 defrest/defrest.asd

Parent

defrest (system)

Location

defrest.asd


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

4.1 defrest-system

Source

defrest.asd

Use List

Previous: , Up: Packages   [Contents][Index]

4.2 defrest

Source

defrest.lisp (file)

Nickname

rest

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: defrest PATTERN METHOD VARLIST &body BODY

Defines a new REST Method. It will listen to urls which match pattern,
have all template blocks replaced and binds variables to varlist.
Returns a dispatcher method, which can be put in the hunchentoot dispatcher
table AND creates an entry in the *rest-dispatcher-table* to be able to defrest
on toplevel.

Usage Example:

(defrest "/greet/{name:.+}" :GET (name)
(format nil "Hello ~a" name))

will create a Hello World Dispatcher which will greet GET /greet/Bonk with ’Hello Bonk’

Package

defrest

Source

defrest.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: create-rest-table-dispatcher &optional TABLE

builds a rest table dispatcher which can be added to the hunchentoot dispatchers to handle all defrest’ed functions

Package

defrest

Source

defrest.lisp (file)

Function: undefrest PATTERN

Removes the rest service with the exact PATTERN from the rest-table-dispatcher

Package

defrest

Source

defrest.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *rest-dispatcher-table*
Package

defrest

Source

defrest.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: create-query-param-parser BINDING &key MANDATORY PATTERN PARAM DEFAULT &allow-other-keys

Compiles the query definition into a function that is to be called with the query parameters of the current request and returns the value of the query parameter

Package

defrest

Source

defrest.lisp (file)

Function: create-rest-dispatcher SCHEMA METHOD QUERY-PARAM-SCHEMES FUN

Creates a hunchentoot compatible dispatcher for a given url SCHEMA, request METHOD and QUERY-PARAM-Schemes which will call the FUN function on match and hands over a parameter map hashtable

Package

defrest

Source

defrest.lisp (file)

Function: mark-template-splitpoints SCHEMA

Returns a list of all split positions to seperate templateblocks in SCHEMA.

Package

defrest

Source

defrest.lisp (file)

Function: parse-schema SCHEMA

splits a schema into blocks representing it’s static parts and it’s placeholders.

Example 1:
’/test/{id:[a-z]+}’ => (’/test/’ (:KEY ’id’ :REGEXP ’[a-z]+’))

Example 2:
’/test/{id:[a-z]?[0-9]+}’ => (’/test/’ (:KEY ’id’ :REGEXP ’[a-z]?[0-9]+’))

Example 3:
’/album/{album:[a-z]+}/track/{track:[0-9]+}’ => (’/album/’ (:KEY ’album’ :REGEXP ’[a-z]+’) ’/track/’ (:KEY ’track’ :REGEXP ’[0-9]+’))

Example 4:
’/album/{album:[a-z]+}/track/{vol:[0-9]+}-{pos:[0-9]+}’ => (’/album/’ (:KEY ’album’ :REGEXP ’[a-z]+’) ’/track/’
(:KEY ’vol’ :REGEXP ’[0-9]+’) ’-’ (:KEY ’pos’ :REGEXP ’[0-9]+’))

Package

defrest

Source

defrest.lisp (file)

Function: parse-uri SCHEMA URI

Parses URI against SCHEMA and returns a hashtable with all pathvariable bindings and as second value the query parameters

Package

defrest

Source

defrest.lisp (file)

Function: parse-varlist VARLIST

Parses the varlist and returns a list of all bindings and a list of the bindings that are mapped to query parameters.

Package

defrest

Source

defrest.lisp (file)

Function: schema->regexpurl SCHEMA

rips out the template blocks and replaces them with their regexp part. eg: {id:[0-9]+} becomes [0-9]+

Package

defrest

Source

defrest.lisp (file)

Function: split-sequence-on-positions SEQ POSLIST

Splits SEQ on all positions listed in POSLIST

Package

defrest

Source

defrest.lisp (file)

Function: split-template-blocks URI

splits an template uri to seperate the template placeholder blocks so that ’/bla/{var:.+}’ becomes (’/bla/’ ’{var:.+}’). best version

Package

defrest

Source

defrest.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   D   F   L   S  
Index Entry  Section

D
defrest.asd: The defrest․asd file
defrest/defrest.asd: The defrest/defrest․asd file
defrest/defrest.lisp: The defrest/defrest․lisp file

F
File, Lisp, defrest.asd: The defrest․asd file
File, Lisp, defrest/defrest.lisp: The defrest/defrest․lisp file
File, static, defrest/defrest.asd: The defrest/defrest․asd file

L
Lisp File, defrest.asd: The defrest․asd file
Lisp File, defrest/defrest.lisp: The defrest/defrest․lisp file

S
Static File, defrest/defrest.asd: The defrest/defrest․asd file

Jump to:   D   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   D   F   M   P   S   U  
Index Entry  Section

C
create-query-param-parser: Internal functions
create-rest-dispatcher: Internal functions
create-rest-table-dispatcher: Exported functions

D
defrest: Exported macros

F
Function, create-query-param-parser: Internal functions
Function, create-rest-dispatcher: Internal functions
Function, create-rest-table-dispatcher: Exported functions
Function, mark-template-splitpoints: Internal functions
Function, parse-schema: Internal functions
Function, parse-uri: Internal functions
Function, parse-varlist: Internal functions
Function, schema->regexpurl: Internal functions
Function, split-sequence-on-positions: Internal functions
Function, split-template-blocks: Internal functions
Function, undefrest: Exported functions

M
Macro, defrest: Exported macros
mark-template-splitpoints: Internal functions

P
parse-schema: Internal functions
parse-uri: Internal functions
parse-varlist: Internal functions

S
schema->regexpurl: Internal functions
split-sequence-on-positions: Internal functions
split-template-blocks: Internal functions

U
undefrest: Exported functions

Jump to:   C   D   F   M   P   S   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*rest-dispatcher-table*: Internal special variables

S
Special Variable, *rest-dispatcher-table*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   D   P   S  
Index Entry  Section

D
defrest: The defrest system
defrest: The defrest package
defrest-system: The defrest-system package

P
Package, defrest: The defrest package
Package, defrest-system: The defrest-system package

S
System, defrest: The defrest system

Jump to:   D   P   S