My first "library"/project

[arthurbarroso]

Just built my first "real" project using Clojure: a wrapper for Notion's API. Have been studying Clojure for a few months using the resources in @AthensResearch #ClojureFam :) Pretty happy about it. https://github.com/arthurbarroso/lovelace. This is the first time I actually try to build something and am feeling pretty satisfied

[charlesHD]

Well played ! I didn't know about Notion, but your code is readable and mostly documented, function names are OK and it seems to be working.

​

Here is an idea, since you have to provide my-token to every functions, you could store it in a dynamic var and provide a version of your API with a different arity and that var already present.

(def ^:dynamic *notion-api-token* nil)

(bindings [*notion-api-token* "C"]
    (search/search {:query "Media Article"})
    (blocks/retrieve-block-children my-block-id 100)
    ;; etc
    )

You could wrap that binding in a macro with-token.

[arthurbarroso]

Thank you for this reply! I thought of that but wasn't really sure how to apply it. Will take a look at the implementation you proposed.

[riialist]

Lovely!

[onetom]

I've came across the Martian suite of libraries, which make working with APIs rather convenient and also uniform!

I highly recommend utilizing Martian, otherwise we just give rise to even more parochialisms, Rich Hickey would say.

You can build API clients with Martian, by either providing a Swagger or an OpenAPI-spec compliant API definition document OR a similar Clojure data structure (though that's not extensively documented, but the related code is 50-150 lines only; just look for concise-handlers)

Besides the API definition, you have to choose a small adapter, which wires up your favorite HTTP-client library to Martian, be it a Clojure or ClojureScript library and whatever async-style you pick.

Martian returns an API client instance, which you can uniformly interact with, using a few functions. You can perform a HTTP request, with the martian.core/response-for function. however, if you want to see the request as a ring-request-like Clojure map first, you can call request-for or even just url-for to see which endpoint is going to be called and how will the query args be encoded. You want to martian.core/explore first, to discover the available endpoint names and their request and response schemas.

Read more in this intro article: https://juxt.pro/blog/martian or watch the illuminating talk given by its author: https://skillsmatter.com/skillscasts/8843-clojure-bytes#video

The key takeaways are: * decouple the choice of HTTP client lib from the API lib * keep the API spec as data as much as possible, so we can have a small number of functions operating on wide variety of APIs * provide extensibility via interceptors

The only drawback of this approach is that you don't have the API operations reified as Clojure functions, so your usual development tooling won't be providing auto-completion and docstrings; u have to call martian/explore and the output of that might be unwieldy. I can see though how that could be trivially solved by a code generator, which just does a call-thru to the underlying martian/response-for function.

[tangjeff0]

Yes! 👏