Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/vermiculus/apiwrap.el

Generate wrappers for your API endpoints!
https://github.com/vermiculus/apiwrap.el

api-wrapper code-generation emacs

Last synced: 3 months ago
JSON representation

Generate wrappers for your API endpoints!

Awesome Lists containing this project

README 

        
#+Title: API-Wrap.el



=API-Wrap.el= is a tool to interface with the APIs of your favorite

services.  These macros make it easy to define efficient and

consistently-documented Elisp functions that use a natural syntax for

application development.



*** Lightning Tour

#+BEGIN_SRC elisp

  (require 'apiwrap)

  (require 'ghub)   ; backend for API primitives -- https://github.com/magit/ghub

  ;; typical backend is <150 lines



  (defun my-github-wrapper--request (method resource params data)

    (ghub-request (upcase (symbol-name method))

                  resource (apiwrap-plist->alist params) data))



  (apiwrap-new-backend "GitHub" "my-github-wrapper"

    '((repo . "REPO is a repository alist of the form returned by `/user/repos'."))

    :request #'my-github-wrapper--request)



  (defapiget-my-github-wrapper "/repos/:owner/:repo/issues"

    "List issues for a repository."

    "https://developer.github.com/v3/issues/#list-issues-for-a-repository"

    (repo) "/repos/:repo.owner.login/:repo.name/issues")



  ;; Check the docstring of this new function!

  (my-github-wrapper-get-repos-owner-repo-issues

   '((owner (login . "magit"))

     (name . "ghub")))

  ;; => parsed response of GET /repos/magit/ghub/issues

#+END_SRC



*** The API Primitive Request

=API-Wrap.el= can't do /all/ of the work for you; you will have to supply

your own primitive request function that can query the API and return

the processed response, but this is expected to be pretty /bare-bones/.

Without duplicating the documentation of ~apiwrap-new-backend~, the

macro expects a function like this:

#+BEGIN_SRC elisp

  (defun api-primitive (method resource params data)

    "Using METHOD, use RESOURCE with PARAMS and DATA.

  METHOD is a symbol -- one of `get', `put', `head', `post',

  `patch', or `delete'.



  RESOURCE is a string, like \"/users/20543/info\".



  PARAMS is a plist of parameters to RESOURCE.



  DATA is an alist of data for RESOURCE (e.g., for posting).")

#+END_SRC



If you have a function like this, you should be good to go!  If you

don't, you can likely model your primitive on =ghub='s (tiny) codebase.



It's not uncommon to need to write a wrapper!  =API-Wrap.el= is written

to be as unassuming as possible.  For instance, ~ghub-request~ does not

take the right kinds of parameters, but we can write a suitable

wrapper as above in the lightning tour.



* Defining API Backends

Suppose I want to use =ghub='s primitives to define a bunch of resource

wrappers to use in my application code.  To do this, I'll use

~apiwrap-new-backend~:

#+BEGIN_SRC elisp

  (require 'apiwrap)



  (eval-when-compile

    (apiwrap-new-backend "GitHub" "my-github-wrapper"

      '((repo . "REPO is a repository alist of the form returned by `/user/repos'.")

        (org  . "ORG is an organization alist of the form returned by `/user/orgs'."))

      :request #'my-github-wrapper--request

      :link (lambda (props)

              (format "https://developer.github.com/v3/%s"

                      (alist-get 'link props)))))

#+END_SRC

Refer to the macro's docstring for full a full description of the

parameters, but take away these highlights:

- we provide a service name that will be referenced in the

  documentation

- we provide a prefix for all macros and functions generated from

  here forward

- we provide an alist of standard parameters with standard

  documentation -- these parameters will be used by my application code

  and are usually similarly structured objects

- we provide a function to generate a link to the official API

  documentation from GitHub -- after all, these are just wrappers!

- we provide a primitive handler to handle making the request

- we provide a means to generate full documentation links based on

  subsequent macro arguments



Note that I must wrap this call (and all function definitions beyond

the primitives) in ~eval-when-compile~ so that =my-github-wrapper.el= will

compile.  If I don't ever need it to compile, I don't need this call.

When I do compile, though, I can rest easy knowing that the macros do

not make it into the byte-code -- only the actual, generated wrapper

functions do.  The macros are only generated once!



This /doesn't/ mean I don't have to ~(require 'apiwrap)~ every time,

though; application code will rely on support functions that evaluate

at runtime (like ~apiwrap-plist->alist~).



* Using the Generated Macros

After evaluating the above call to ~apiwrap-new-backend~, you will have six

new macros for your use:

- ~defapiget-my-github-wrapper~

- ~defapiput-my-github-wrapper~

- ~defapihead-my-github-wrapper~

- ~defapipost-my-github-wrapper~

- ~defapipatch-my-github-wrapper~

- ~defapidelete-my-github-wrapper~

These wonderful new macros super-charge your primitive API functions

into documentation-generating, resource-wrapping machines!  Let's

define a wrapper for the GitHub API endpoint =GET /issues=.



*** A simple use-case

Here is the definition of ~my-github-wrapper-get-issues~:

#+BEGIN_SRC elisp

  (defapiget-my-github-wrapper "/issues"

    "List all issues assigned to the authenticated user across all

  visible repositories including owned repositories, member

  repositories, and organization repositories."

    "issues/#list-issues")

#+END_SRC

If we refer to the documentation of ~defapiget-my-github-wrapper~, we'll

see that =/issues= is the method call as written in [[https://developer.github.com/v3/issues/#list-issues][the linked GitHub

API documentation]].  A brief docstring is provided, here copied from

the API.



If we now inspect the documentation of ~my-github-wrapper-get-issues~,

we'll see all of our information included in the docstring:

#+BEGIN_EXAMPLE

  my-github-wrapper-get-issues is a Lisp function.



  (my-github-wrapper-get-issues &optional DATA &rest PARAMS)



  List all issues assigned to the authenticated user across all

  visible repositories including owned repositories, member

  repositories, and organization repositories.



  DATA is a data structure to be sent with this request.  If it’s

  not required, it can simply be omitted.



  PARAMS is a plist of parameters appended to the method call.



  --------------------



  This generated function wraps the GitHub API endpoint



      GET /issues



  which is documented at



      URL ‘https://developer.github.com/v3/issues/#list-issues’

#+END_EXAMPLE

In addition to the documentation we provided, the =DATA= and =PARAMS=

parameters have been added to the function and appropriately

documented.  At the end of the documentation, we report that the

function was generated from a raw method call and where that method is

fully documented (e.g., what =PARAMS= it accepts, what the format of

=DATA= is, the structure of its response, etc.).



*** On-the-fly parameters

Each function defined with the ~defapi*-my-github-wrapper~ macros

accepts =PARAMS= as a =&rest= argument.  This argument is effectively a

list of keyword arguments to the method call -- similar to how =&keys=

works in Common Lisp.  However, collecting them as a list allows us to

perform generic processing on them (with ~apiwrap-plist->alist~) so that

they can be passed straight to the request primitive.  For example,

#+BEGIN_SRC elisp

  ;; retrieve closed issues

  (my-github-wrapper-get-issues :state "closed")

#+END_SRC



If I wanted to use =:state 'closed= instead, I would need to handle that

in my primitive function (in this case, ~my-github-wrapper--request~).

For example, if I wanted to convert symbols to strings, I could modify

the function to say the following:

#+BEGIN_SRC elisp

  (defun my-github-wrapper--request (method resource params data)

    (ghub-request

     (upcase (sumbol-name method))

     resource

     (my-github-wrapper--preprocess-params params)

     data))



  (defun my-github-wrapper--preprocess-params (alist)

    (mapcar (lambda (cell)

              (if (symbolp (cdr cell))

                  (cons (car cell) (symbol-name (cdr cell)))

                cell))

            alist))

#+END_SRC



*** A complex use-case

Of course, many method calls accept 'interpolated' parameters

(so-called for lack of a better phrase).  Thanks to some very slick

macro-magic, ~defapi*-my-github-wrapper~ can handle these, too!



Consider this definition of

~my-github-wrapper-get-repos-owner-repo-issues~:

#+BEGIN_SRC elisp

  (defapiget-my-github-wrapper "/repos/:owner/:repo/issues"

    "List issues for a repository."

    "issues/#list-issues-for-a-repository"

    (repo) "/repos/:repo.owner.login/:repo.name/issues")

#+END_SRC

We've provided two extra parameters: =repo= and the string

=/repos/:repo.owner.login/:repo.name/issues=. Since

~defapiget-my-github-wrapper~ is a macro, =repo= is a just a symbol that

will be used in the argument list of the generated function (and

inserted into its docstring according to

~my-github-wrapper--standard-parameters~).



This second string is where things get interesting.  This argument

overrides the first, as-advertised method call for a very specific

purpose: when our new function is used, this string is evaluated in

the context of our =repo= object using syntax akin to ~let-alist~:

#+BEGIN_SRC elisp

  ;; repo "/repos/:repo.owner.login/:repo.name/issues"

  (my-github-wrapper-get-repos-owner-repo-issues

   '((owner (login . "vermiculus"))

     (name . "apiwrap.el")))

  ;; calls GET /repos/vermiculus/apiwrap.el/issues

#+END_SRC



*** Multiple required parameters

You may have noticed that you provided the =repo= symbol above in a

/list/.  You can have as many symbols as you want in this list; they

will all be evaluated in the string described above:

#+BEGIN_SRC elisp

  (defapiget-my-github-wrapper "/repos/:owner/:repo/issues/:number/comments"

    "List comments on an issue."

    "issues/comments/#list-comments-on-an-issue"

    (repo issue) "/repos/:repo.owner.login/:repo.name/issues/:issue.number/comments")

#+END_SRC

Each =:object= is considered for evaluation:

#+BEGIN_SRC elisp

  ;; repo issue "/repos/:repo.owner.login/:repo.name/issues/:issue.number/comments"

  (my-github-wrapper-get-repos-owner-repo-issues-number-comments

   '((owner (login . "vermiculus"))

     (name . "apiwrap.el"))

   '((number . 1)))

  ;; calls GET /repos/vermiculus/apiwrap.el/issues/1/comments

#+END_SRC



It's recommended that you treat each interpolated parameter as a full

object.  For example, I could've defined the above as

#+BEGIN_SRC elisp

  (defapiget-my-github-wrapper "/repos/:owner/:repo/issues/:number/comments"

    "List comments on an issue."

    "issues/comments/#list-comments-on-an-issue"

    (repo number) "/repos/:repo.owner.login/:repo.name/issues/:number/comments")

#+END_SRC

but I would not be able to pass an issue object into the function

without first getting its number out of the object.  If desired,

convenience functions can easily be written to create the sparse

object necessary to complete the API call:

#+BEGIN_SRC elisp

  (defun my-github-wrapper-issue-get-comments (repo issue-number)

    (my-github-wrapper-get-repos-owner-repo-issues-number-comments

     repo `((number . ,issue-number))))

#+END_SRC



*** Handling Errors

When writing a request primitive, it is usually wise to signal an

error for abnormal responses usually anything that's not =HTTP 2xx=.

Some API endpoints, however, may intentionally return an 'error'

status that in fact should not be considered an /error/ at all.  Take

for example the following GitHub API endpoint:

#+BEGIN_EXAMPLE

GET /repos/:owner/:repo

#+END_EXAMPLE

This returns the repository object if it exists and HTTP 404 if it

does not.  By convention, a wrapper function should probably return

=nil= instead to indicate there was nothing there.  This is where the

=:condition-case= keyword argument comes in:

#+BEGIN_SRC elisp

  (defapiget-my-github-wrapper "/repos/:owner/:repo"

    "Get a specific repository object."

    "repos/#get"

    (repo) "/repos/:repo.owner.login/:repo.name"

    :condition-case

    ((ghub-404 nil)))

#+END_SRC

Now, on receiving the =ghub-404= signal,

~my-github-wrapper-get-repos-owner-repo~ will return =nil= instead of

passing that error back up to the caller.



It's recommended that this configuration is not used at the

~apiwrap-new-backend~ level and instead left to each specific endpoint

per that endpoint's documentation.  Errors should still be errors --

think twice before you add any 'fancy' error-handling here.



** Other configuration

=API-Wrap.el= aims to be configurable enough to suit all kinds of needs.

Each call to ~defapi*-my-github-wrapper~ can take optional keyword

arguments as well.  These keyword arguments can override the default

values given in ~apiwrap-new-backend~.

* Using Macro-Generated Wrappers

This is the fun part!  The wrappers are a joy to use:



#+BEGIN_SRC elisp

  ;;; GET /issues

  (my-github-wrapper-get-issues)



  ;;; GET /issues?state=closed

  (my-github-wrapper-get-issues :state 'closed)



  (let ((repo (ghub-get "/repos/magit/magit")))

    (list

     ;; Magit's issues

     ;; GET /repos/magit/magit/issues

     (my-github-wrapper-get-repos-owner-repo-issues repo)



     ;; Magit's closed issues labeled 'easy'

     ;; GET /repos/magit/magit/issues?state=closed&labels=easy

     (my-github-wrapper-get-repos-owner-repo-issues repo

       :state 'closed :labels "easy")))

#+END_SRC

As an exercise, how would you wrap =(ghub-get "/repos/magit/magit")=?



I hope you enjoy using =API-Wrap.el= as much as I've enjoyed writing it!