This is the restful Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:36:12 2024 GMT+0.
restful/restful.asdrestful/src/package.lisprestful/src/condition.lisprestful/src/storage.lisprestful/src/storages/memory.lisprestful/src/resource-metaclass.lisprestful/src/slot.lisprestful/src/resource.lisprestful/src/collection.lisprestful/src/http.lisprestful/src/acceptor.lispThe main system appears first, followed by any subsystem dependency.
restfulSpin up new REST entities like madman
Florian Margaine <florian@margaine.com>
MIT License
hunchentoot (system).
alexandria (system).
cl-ppcre (system).
jonathan (system).
closer-mop (system).
src (module).
Modules are listed depth-first from the system components tree.
restful/srcrestful (system).
package.lisp (file).
condition.lisp (file).
storage.lisp (file).
storages/memory.lisp (file).
resource-metaclass.lisp (file).
slot.lisp (file).
resource.lisp (file).
collection.lisp (file).
http.lisp (file).
acceptor.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
restful/restful.asdrestful/src/package.lisprestful/src/condition.lisprestful/src/storage.lisprestful/src/storages/memory.lisprestful/src/resource-metaclass.lisprestful/src/slot.lisprestful/src/resource.lisprestful/src/collection.lisprestful/src/http.lisprestful/src/acceptor.lisprestful/src/condition.lispsrc (module).
permission-rejected (condition).
request-data-missing (condition).
resource-not-found-error (condition).
restful/src/storage.lispsrc (module).
delete-item (generic function).
get-item (generic function).
get-items (generic function).
save-item (generic function).
restful/src/storages/memory.lispsrc (module).
delete-item (method).
get-item (method).
get-items (method).
memory-storage (class).
save-item (method).
storage (reader method).
restful/src/resource-metaclass.lispsrc (module).
compute-effective-slot-definition (method).
direct-slot-definition-class (method).
effective-slot-definition-class (method).
resource-metaclass (class).
validate-superclass (method).
restful/src/slot.lispsrc (module).
find-identifier-slot (function).
get-resource-slots (function).
is-slot-excluded (function).
normalize-keyword (function).
normalize-keywords (function).
normalize-resource (function).
populate-slot (function).
slot-default-value (function).
slot-is-required (function).
restful/src/resource.lispsrc (module).
%to-json (method).
create-resource (generic function).
delete-resource (generic function).
has-permission (generic function).
load-resource (generic function).
parent (reader method).
patch-resource (generic function).
replace-resource (generic function).
resource (class).
resource-action (generic function).
storage (reader method).
view-resource (generic function).
equal-resource (function).
populate-resource (function).
restful/src/collection.lispsrc (module).
collection (class).
parent (reader method).
storage (reader method).
view-collection (generic function).
class-of-resource (reader method).
populate-resources (function).
restful/src/acceptor.lispsrc (module).
acceptor (class).
acceptor-dispatch-request (method).
handle-collection (function).
handle-delete-resource (function).
handle-get-resource (function).
handle-patch-resource (function).
handle-post-resource (function).
handle-put-resource (function).
handle-resource (function).
handle-resource-method (function).
handle-uri (function).
Packages are listed by definition order.
restfulcommon-lisp.
acceptor (class).
collection (class).
create-resource (generic function).
delete-item (generic function).
delete-resource (generic function).
get-item (generic function).
get-items (generic function).
has-permission (generic function).
load-resource (generic function).
memory-storage (class).
parent (generic reader).
patch-resource (generic function).
permission-rejected (condition).
replace-resource (generic function).
request-data-missing (condition).
resource (class).
resource-action (generic function).
resource-metaclass (class).
resource-not-found-error (condition).
save-item (generic function).
storage (generic reader).
view-collection (generic function).
view-resource (generic function).
class-of-resource (generic reader).
equal-resource (function).
find-identifier-slot (function).
get-resource-slots (function).
handle-collection (function).
handle-delete-resource (function).
handle-get-resource (function).
handle-patch-resource (function).
handle-post-resource (function).
handle-put-resource (function).
handle-resource (function).
handle-resource-method (function).
handle-uri (function).
http-error (function).
is-slot-excluded (function).
normalize-keyword (function).
normalize-keywords (function).
normalize-resource (function).
populate-resource (function).
populate-resources (function).
populate-slot (function).
resource-standard-direct-slot-definition (class).
resource-standard-effective-slot-definition (class).
slot-default-value (function).
slot-is-required (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Creates a new resource based on the request data.
Deletes a single item in the storage.
memory-storage) identifier) ¶Deletes the item from the hash table. The identifier is the key of the hash table.
Deletes an existing resource.
Gets a single item in the storage. Returns a plist.
memory-storage) identifier) ¶Gets a single item according to its identifier. Returns a plist. The identifier is the key of the hash table.
Gets all the items available in the storage.
This should be overridden for a specific storage if sorting/filtering
options want to be added.
Returns a list of plists.
memory-storage)) ¶Gets all the items stored in the current instance.
Determines if the request has permission to hit the resource. If it doesn’t, returns NIL.
Loads a resource based on its identifier.
collection)) ¶The parent resource, if any. If there’s no parent, its value is NIL.
Patches an existing resource based on the request data.
Replaces a resource based on the request data.
Lets you handle actions on the resource.
The :identifier slot lets you know which action is called. This
method is called for the POST requests, and routing should
be handled by yourself. Here is a typical example of what
it can look like:
(defmethod restful:resource-action ((res custom-resource)) (cond ((string= (identifier res) "login") #’handle-login) (t (http-page-not-found))))
Saves an item in the storage, creating it if needed.
Since resources are created or updated with PUT requests, as long as you have an ID, a resource exists. Except if the user doesn’t have permission to PUT non-existing resources, but that’s handled at the application level, not at the storage level, which only cares that a resource has an identifier.
memory-storage) resource) ¶Saves or updates an item in the hash table. Since ‘(setf (gethash [...]))‘ is used, the ’save or update’ feature is very simply done.
collection)) ¶The storage object that satisfies the interface of the ‘restful:storage‘ class.
resource)) ¶The storage object that satisfies the interface of the ‘restful:storage‘ class.
memory-storage)) ¶The hash table used to store the items in memory.
Returns an object that will be
serialized to json using the jonathan library.
collection)) ¶Returns an object populated by the collection’s storage.
Returns an object that will be serialized to json using the jonathan library.
resource)) ¶Serializes a resource to json using the jonathan library.
jonathan.encode.
acceptor) request) ¶Dispatches requests to the internal handle-uri function if the request matches the requirements. Namely, accepting application/json.
This method also defines the application/json response header.
This method catches the following errors:
- ‘resource-not-found-error‘: returns a 404 page not found response.
- ‘request-data-missing‘: returns a 400 bad request response.
- ‘permission-rejected‘: returns a 403 forbidden response.
- ‘error‘: returns a 500 internal server error response.
hunchentoot.
resource-metaclass) name direct-slot-definitions) ¶sb-mop.
resource-metaclass) &rest initargs) ¶sb-mop.
resource-metaclass) &rest initargs) ¶sb-mop.
resource-metaclass) (superclass standard-class)) ¶sb-mop.
Raised when a request doesn’t have access to the
requested resource.
This error is raised when the has-permission method of a resource
returns NIL.
When this error is handled, the response will have the 403 status
code.
This error can be raised with every method.
error.
Raised when a request body doesn’t fulfill the
resource’s schema.
For example, if a resource is the following:
(defclass foo (restful:resource)
((id :is-identifier t)
(name :required t))
(:metaclass restful:resource-metaclass))
And the request body is the following:
{"id":"bar"}
This error will be raised.
When this error is handled, the response will have a 400 status
code.
This error can be raised in the following requests: PUT, POST.
error.
Raised when a request resource is not found.
When this error is handled, the response will have the 404 status
code.
This error can be raised in the following requests: GET, PATCH, DELETE, POST.
error.
Base class for the acceptor, subclassing
a hunchentoot acceptor to be able to handle incoming requests.
This class defines the following slot:
- ‘resource-definition‘: defines the list of resources and
how to handle them. This is a hash table that must:
- define a string key being the prefix for the resources
- for each key, define a value being a hash table. This
hash table must:
- define a keyword key named ‘:class‘ being the resource
class.
- define a keyword named ‘:collection‘ being the collection
class.
- define a keyword named ‘:storage‘ being the storage instance.
- define a keyword named ‘:children‘ being a new resource
definition, if necessary.
This is an example of a resource definition (assuming the readers
macros to define hash tables using brackets):
{
"article" {
:class ’article
:collection ’restful:collection
:storage (make-instance ’restful:memory-storage)
:children {
"comment" {
:class ’comment
:collection ’restful:collection
:storage (make-instance ’restful:memory-storage)
}
}
}
}
The API will be available through the following endpoints:
- ‘/article‘: collection endpoint.
- ‘/article/foo‘: resource ’foo’ of instance ‘article‘ endpoint.
- ‘/article/foo/comment/bar‘: resource ’bar’ of instance ‘comment‘,
having for parent ’foo’ of instance ‘article‘ endpoint.
This class should be used to instantiate objects to be used
with hunchentoot.
Here is an example of such usage:
(hunchentoot:start
(make-instance ’restful:acceptor
:port 4242
:resource-definition *resource-definition*))
acceptor.
The resource definition, documented in the class documentation.
hash-table
:resource-definition
Base class for restful collections. There’s
not much reason to extend it with the current features.
The parent resource, if any. If there’s no parent, its value is NIL.
:parent
This slot is read-only.
The storage object that satisfies the interface of the ‘restful:storage‘ class.
:storage
This slot is read-only.
The resource’s class of this collection.
:class-of-resource
This slot is read-only.
Restful’s storage by storing the data in memory.
This is of course not very good for persistence matters (duh), but is
perfect for development, and simply to show how a storage class
can be built.
This storage just uses a hash table stored in a slot.
Base class for resources. All the resources
should extend this class to have the default (required) slots.
Stores the parent of the resource in case of
hierarchy. For example, if hitting foo/bar/baz/qux, the resource
with identifier ’qux’ will have ’bar’ as parent. If there’s no
parent, its value is NIL.
restful:resource
:parent
This slot is read-only.
The metaclass for resources, required to be
used by all the resources.
This metaclass allows resources to use new slot options:
- ‘is-identifier‘: defaults to NIL. Only one slot per resource
should set this option to T. It will make the slot the identifier
of the resource. The identifier is used to find the resource in
the API. When set to T, the slot option ‘required‘ is implicitly
set to T too.
- ‘required‘: defaults to NIL. When set to T, this slot will
be required in the API requests.
- ‘default‘: defaults to ‘""‘. If the slot is not required,
this value will be used to fill in the slot value if no value
is provided.
- ‘excluded‘: defaults to NIL. When to set T, this slot will be
ignored for the resource’s CRUD actions. For example, the
‘restful:resource‘ class uses it for its ‘parent‘ and ‘storage‘
slots.
standard-class.
collection)) ¶The resource’s class of this collection.
| Jump to: | %
A C D E F G H I L M N P R S V |
|---|
| Jump to: | %
A C D E F G H I L M N P R S V |
|---|
| Jump to: | C D E I P R S |
|---|
| Jump to: | C D E I P R S |
|---|
| Jump to: | A C F H M P R S |
|---|
| Jump to: | A C F H M P R S |
|---|