rest db service

[grantmacken]

One of the thing I had in mind for issue #48 was to create the basis for establishing services based the cowboy rest handler and a main module server.

Both exist-db and baseX have generic service URI patterns

For baseX

The following services are available and enabled by default: 

RESTXQ     |  /           | Write enriched APIs and full web applications with XQuery.
WebSockets |  ws/         | Bidirectional client/server communication.
REST       |  rest/       | Straightforward access to XML databases and its resources.
WebDAV     |  webdav/     | Database access via the file system.
Default    |  static/     | Access to static server resources (HTML, JavaScript, CSS, images, …).

existdb also has similar uri based services with the preferred one for interaction with the exist db being the web rest api http://localhost:8080/exist/rest/ @see https://exist-db.org/exist/apps/doc/devguide_rest

With pr #52 we have the following URI service patterns

 '/'   -   handled by the cowboy generic handler serves content provided by restXQ library module routes and http constraints
'/assets/'  -  handled by the cowboy static assets handler serves content in priv/static/assets 
' /xqerl'   -  handled  by the cowboy rest handler serves a welcome page provided be xQuery main module 'greeter.xq'  

so to extend this like baseX and existdb we would have

' /rest/'   -   handled  by cowboy **rest handler** serves direct access to xqerl databases, collections and XDM items

uri template: /rest/{domain}/{path-to-collection} => collection handler /rest/{domain}/{path-to-collection}/item => item handler the handlers being cowboy rest handler with xquery main modules doing the work interacting with the xqerl db

rest web interface for xqerl database collections collections: /rest/{domain}/{path-to-collection} GET - lists uri items is collection POST - create item for collection DELETE - delete collection OPTIONS - list request methods and request allowed post body types for collection HEAD - collection availabilty

rest web interface for xqerl database items resources: /rest/{domain}/{path-to-collection}/item GET - get item in collection PUT - update item DELETE - delete item HEAD - item availabilty

and maybe patch using xquery updating expression derived from a uri like resources: /rest/{domain}/{path-to-collection}/item?{type=update&key=value} PATCH - update key value in item

or maybe xquery updating expression can be derived from a JSON or XML body included in the PATCH request

[grantmacken]

@zadean thanks for merging this. I think it will make it easier to use xqerl as a backend datastore for SPAs and web app servers

There is still work to be done!

• [ ] collection query filters: a GET on collections could quite large, so some form of pagination filter based on query params might be good. http://localhost:8081/db/example.com/docs?limit=20

• [ ] more post items: csv content-type stored as a XDM array item, could be retrieved with Accept header as either a serialized JSON array or text or maybe a standard XML csv serialization if there is one

• [ ] markdown My current strategy is to process Markdown in advance using cmark and storing cmark output as a XDM document-node. With a Accept header the cmark XML document node code could be retrieved as the serialised XML node or a transform of the node into a HTML representation or a text representation ( the original markdown txt) An alternative would be for xqerl to somehow process the markdown text before it stores it.

• [ ] documentation. Apart from the github runner checks, which should show what the feature can do, I need to write up something