Most "pythonic" syntax to use for an API client library

[Chris Angelico]

On Mon, Apr 29, 2019 at 2:43 PM DL Neil <PythonList at danceswithmice.info> wrote:
>
> On 29/04/19 3:55 PM, Chris Angelico wrote:
> > On Mon, Apr 29, 2019 at 1:43 PM DL Neil <PythonList at danceswithmice.info> wrote:
> >> Well, seeing you ask: a more HTTP-ish approach *might* be:
> >>
> >> api.update.customer( 1, name='Bob' )
> >>
> >> ie
> >> api.verb.subject( adjectives and adverbs )
> >>
> >> Thus:
> >> api_label/intro/ID.what_we're_going_to_do.who/what_we'll_do_it_to(
> >> customerID, support_data)
> >>
> >> Yet, it doesn't really *look right* does it?
> >> (and someone might complain about mixing the 'different' variable-values...)
> >>
> >
> > The point here is not to make an HTTP-like interface, but a
> > Python-like interface :)
>
> OK, I'll bite...
>
> ...shouldn't the Python-like interface reflect what it is wrapping?

It should. But if you just want an HTTP-like interface, you don't
really need much of a wrapper. All you need is a hyperthin wrapper
around the requests library - something like:

api.post("customer", {...})
api.get("customer", 1)
api.patch("customer", 1, {...})

And that's fine if what you want is HTTP. But if you want something a
bit more Pythonic, you want something that more adequately represents
the underlying concepts, not the intermediate transport layer. In this
case, the concepts are customers (and, presumably, other types of
queryable information), and the things you can do with them (get info,
update info, enumerate, create).

There may be some useful inspiration to be gained from looking at database ORMs.

ChrisA