Moooing away in Common Lisp

I'v recently found myself needing to use a task manager to make some bulk operations (to be more precise, I wanted to copy all of my tasks to a device with no built-in synchronization mechanism for those). I happen to make use of the great Remember The Milk Web application (I've previously worked with Emacs Planner, but I had to drop it in favor of a more mobile version of my life).

Enter Common Lisp. Perhaps the fastest way to do some scripting in my mind, but I've yet to make a library to use a Web-based API. Turned out it was quite clean, and in about 5 hours of work I had the whole API grokked, coded, tested and hosted in GoogleCode here. (I looked into cl.net, but found the google's approach to hosting much more featured for the fast start I was looking for. If this has enough momentum I can look into it again, with more time - the main advantage would be asdf-installability, I suppose.)

I already had experience making project "skeletons" (asdf project file, package declaration, etc.). So the hardest thing I had to do was look into the web API call mechanism and into the md5 encryption. If you don't need the detailed description, tha answers are, respectively, Drakma and Ironclad. ( I also use cl-json to parse RTM's responses into a lisp-friendly format.)

To call a Web-based method, we need to make an HTTP request, and be able to read the response. using drakma (asdf installable and loaded in the usual way), all I had to do was something like:

(http-request rtm-api-endpoint :method :post :parameters '(("param-name" . "param-value")))

With some parameter abstractions, RTM's was easily tamed. A call to one of their methods is now made with the following macro:

(defun rtm-api-call-method (method &optional key-value-pairs &key with-timeline with-authentication (format "json"))   "Calls `METHOD'.  - Optionally passes pairs of strings in `KEY-VALUE-PAIRS' in the form of (`PARAMETER' . `VALUE').  - Keyword `WITH-TIMELINE', if not null, allows the method to be called within the `*CURRENT-TIMELINE*'.  - Keyword `WITH-AUTHENTICATION', if not null, allows the method call to be authenticated with a valid `*RTM-API-TOKEN*'.  - Keyword `FORMAT' is one of \"json\" (the default value) or \"rest\", and specifies the server reply format."   (declare (special *current-timeline*))   (let* ((parameters `(("api_key"    . ,rtm-api-key)                        ("method"     . ,method)                        ("format"     . ,format)                        ,@(when with-timeline                                (with-timeline                                  `(("timeline" . ,*current-timeline*))))                        ,@(when with-authentication                             `(("auth_token" . ,*rtm-api-token*)))                        ,@key-value-pairs))          (api-sig (compute-rtm-api-sig parameters)))     (multiple-value-bind (result)         (http-request rtm-api-endpoint                       :method :post                       :parameters `(                                     ,@parameters                                     ("api_sig" . ,api-sig)))       (let* ((response (json-bind (rsp) result rsp))              (stat (assoc :stat response)))         (cond           ((string=  (cdr stat) "ok")            (rest response))           ((string=  (cdr stat) "fail")            (let ((err-info (cdr (assoc :err response))))              (error "RTM error code ~a: ~a~%" (cdr (assoc :code err-info))                     (cdr (assoc :msg err-info))))))))))

With this (rather big, for the sake of readability, or mayhap due to my lack of experience in mental pretty printing) function, I define a call to an RTM module simply by coding:

(defun rtm-api-tasks-complete (list-id taskseries-id task-id)   (rtm-api-call-method "rtm.tasks.complete"                        `(("list_id"       . ,list-id)                          ("taskseries_id" . ,taskseries-id)                          ("task_id"       . ,task-id))                        :with-authentication t                        :with-timeline t))

The only call in the first function definition that cannot be easily guessed how they work is the compute-rpm-api-sig-parameters. This is the function that performs the algorithm required by RTM to encode all parameters and guarantee authenticity in each request (along with a masked API key). Basically it does some mambo-jumbo concatenation with each parameter's name and value, and then performs an MD5 to get the equivalent hash code. Easy, right? But I'm a lazy programmer. That, and I truly believe there's no point in reinventing the wheel, so I looked for encryption functions in Lisp, and I found Ironclad, a collection of most of these functions in Lisp. So producing an md5 functions was as easy as the following:

(defun md5 (string)   "MD5 uses ironclad to encode `STRING' into an hexadecimal digest string."   (ironclad:byte-array-to-hex-string    (ironclad:digest-sequence :md5 (ironclad:ascii-string-to-byte-array string))))

And that's about it. The rest was toying around, the API works perfectly (kudos to the RTM dev team!), and I was thrilled to have my tasks exported in a jiffy. If you want to find more info, feel free to snoop through the code (it's quite easy to grasp, I think, and relatively small), in the Google Code site: http://code.google.com/p/rtm-lisp-api/ . So now, what would you, gentle reader, do with this API? Drop me some comments with your ideas.

Until the next time!