Common Lisp support for the Etsy API
Common Lisp
Switch branches/tags
Nothing to show
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