Common Lisp support for the Etsy API
Common Lisp
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
misc
.gitignore
README
TBD
TODO
api-utils.lisp
base.lisp
cl-etsy.asd
main.lisp
methods.lisp
packages.lisp
tests.lisp
types.lisp

README

CL-Etsy bridges from Common Lisp to version 1 of the Etsy.com API[2].  It is an asdf[1].  Once loaded the common lisp package "ETSY" exports one routine for each method in the API, and classes for user, shop, listing, and api-method.

The names used in the API specification use two spelling conventions.  Camel case is used for method names, e.g. getUserDescription.  In cl-etsy these are converted to the usual lisp spelling, e.g. get-user-description.  Underscores are used for field names, e.g. user_name.  In cl-etsy these are converted to the usual Lisp spelling, e.g. user-name.

All routines in the API two values a list of results and a count.  For example here we look for the first 3 users of the name "benjamin".

  ETSY> (get-users-by-name "benjamin" :limit 3  :detail-level :high)
  (#<USER 7123275: BenjaminHart2008> #<USER 7059119: benjamin6>
   #<USER 7026092: benjamin315>)
  128
  ETSY> 

Note the count is tells you how many results are available in total.  But it is
occationally the length the list of results.

It is uniform, if a bit counter intuitive, that routines that always return a
single value also follow this pattern.  For example:

  CL-USER> (etsy:get-server-epoch)
  (1238167857)
  1
  CL-USER> (etsy:ping)
  ("pong")
  1
  CL-USER> (etsy:get-user-details 93)
  (#<ETSY:USER 93: Rokali>)
  1
  CL-USER> 

Error are, at present, signaled by invoking error.  All http requests that
return other than HTTP code 200 signal an error.  For example:

  CL-USER> (handler-case (print (etsy:get-user-details 1)) (error (c) (format t "~A" c)))
  Failed API call 404 user_id 1 does not exist
  NIL
  CL-USER> (handler-case (print (etsy:get-user-details "bob/slash")) (error (c) (format t "~A" c)))
  Failed API call 404 Can't route command: /users/bob/slash
  NIL
  CL-USER> 

Of course before any of this works you will need to register[2] and then
create a "application"[4] so you have an an API KEY.  Then store that into
*API-KEY*, i.e.:

  (setf esty:*api-key* "thisreallyisnotanapikey")

CL-Etsy requires cl-ppcre, drakma, and cl-json.

If you have the testing utlity FiveAM[5] loaded when you load the system then you get a modicum of
testing as defined in the tests.lisp file; you can run these by doing: (fiveam:run! etsy::etsy-api).

[1] http://common-lisp.net/project/asdf/
[2] http://developer.etsy.com/docs
[3] http://developer.etsy.com/member/register
[4] http://developer.etsy.com/apps/myapps
[5] http://common-lisp.net/project/bese/FiveAM.html