What's the state of this project?

[afidegnum]

I m looking for a project like this but it's been a while it has been developed, what's it's status?

[gschjetne]

Pretty much dead, unfortunately. The project this was used for was cancelled. What kind of project did you have in mind?

[afidegnum]

Well, arangodb was a de-facto db I have adopted for some times now, and i started to work on CL, then i chanced on this repo, i wanted to make use of it to develop future projects.

[gschjetne]

If you want you can take over maintainership.

The code quality may not be stellar, and it's heavily dependent on the jsown JSON library, I've been meaning to find a good way of writing these kinds of DB client libraries in a way where the user can decide on which library to use, or maybe write a lazy parser that only extracted what was necessary for the library to function, and leave the rest to the user.

The most useful part is probably in rest.lisp. Whether or not you decide to keep the def-arango-fun macro, it has a large portion of the ArangoDB API defined, which is probably the most tedious task of writing such a library.

[afidegnum]

I will be glad, I have already been using arangodb with Python-arango which i m very versatile of, I will be glad to update the code base to the latest stable release, I was reading the API documentation and plan to develop CL version of it till i decided to search on Github and I discovered your repo.

I would love to help improve the coding quality as well

[gschjetne]

Feel free to fork it, or simply clone the repo and put it under your account. Once you're up and running I'll put a notice here saying yours is the canonical repository.

[afidegnum]

ok, i have forked it,

meanwhile, can you provide a short starting documentation? maybe some necessary steps to take and libraries requirement, calling of objects, etc... and i will take it from there.

[gschjetne]

Here's an overview of the most important bits to get you started. Don't hesitate asking specific questions as you go along:

requests.lisp

def-arango-fun

This crucial part, which forms a DSL for defining different ArangoDB API calls. It's what defines the bindings to ArangoDB's API.

Syntax

def-arango-fun name lambda-list method option*

option::= (:documentation docstring)
          (:uri uri)
          (:query query)
          (:content content)

uri::= (component*)

query::= ([argument value]*)

Arguments and Values

name---the name of the function lambda-list---the lambda list of the function method---the HTTP method to use documentation---the function's docstring uri---a list of URI components query---a list of query arguments, where the odd elements are arguments and even elements are the corresponding values, in plist fashion. content---a JSOWN expression that will be sent as the request body.

Todo

You should probably add an option for a callback for processing the response. By default it just parses the JSON response from ArangoDB and returns it, which works well in almost all the cases. One example of an exception is read-document-header needs special processing, and currently always results in a failure.

format-uri

Take the parts of the URI and turn into a string

Syntax

format-uri &key uri query database => string

Arguments and values

uri---a list of URI components query---a list of query arguments, where the odd elements are arguments and even elements are the corresponding values, in plist fashion. database---the name of the database to access

Todo

This can probably be replaced by a relatively simple application of format. But you might also consider the need for URL-encoding your strings if they contain reserved characters. Quri might be a good library for this.

send-request

Responsible for carrying out the REST call specified through the def-arango-fun macro, and parsing and returning the result.

Syntax

send-request &key method uri content username password => parsed JSON structure

Arguments and Values

method---the HTTP method to use uri---the URI, as a string content---the request body, as a string username---the username password---the password

Todo

It's probably best to rewrite this entirely, the code quality isn't terribly good, and I don't know if it's the most efficient way to do it.

rest.lisp

Contains all the API methods defined to date. Structured after the ArangoDB API documentation (at the time it was written), and the gaps should be evident by the comments. Most of these should be fine as they stand, but if you decide to move away from JSOWN you'd have to make substantial changes. As I said before, perhaps you should take a JSON library-agnostic approach.

Other suggestions

CLOS abstraction

A higher level API based on CLOS may be useful for users who don't want to deal directly with REST calls. For example, I have written a generic library for mapping JSON and CLOS objects with this sort of applications in mind, JSON-MOP

Asynchronous requests

A common (anti-)pattern in NoSQL is having to make multiple requests and assembling the results client-side. This is less of a problem in ArangoDB thanks to AQL, but it still might be useful to have the functions defined in rest.lisp return promises, or in Java parlance, futures, instead of blocking, so multiple requests can be done in parallel.

Error handling

Currently it signals arango-error on failure, which contains the HTTP status, ArangoDB error code and description. However it might be useful to make each distinct ArangoDB error its own subclass of arango-error for simpler error handling on the part of the user.

[gschjetne]

@afidegnum have you had any luck with this?