Main API for the Blip library

[reborg]

Discussing with @herichovadajana we agreed that the following could be a good interface to interact with the Blip library:

(def grapqhql-request 
  (blip/init
   (slurp "test/blip/test-query.graphql")
   {:endpoint "http://localhost:2021"}))

(grapqhql-request "query-entity" {:id "entity-id"}) ;; get entity by ID
(grapqhql-request "mutation-create-entity" {:id "entity-id" :name "blah"}) ;; create entity

When Site is involved (or any other graphql engine that requires more than just an endpoint) we could pass more initialisation parameters, for example:

(def grapqhql-request 
  (blip/init
   (slurp "test/blip/test-query.graphql")
   {:endpoint "http://localhost:2021"
    :headers (assoc "authorization" (str "Bearer " (site/get-site-token site-auth)))}))

[reborg]

Also pretty important: grapqhql-request input/output should take/return idiomatic Clojure data structures, that is {:id 1 :last-name "jack"} and not {"id" 1 "lastName" "jack"}. This is because GraphQL will likely take and return json, so some conversion between formats is necessary (and Blip can do that).

[reborg]

Some more details from chatting around on Slack. If we want Site to be more Site-friendly, we could have a blip.site namespace which specialises with tokens and whatnot. So the interaction in that case could be:

(require '[blip.site :as site])

(def site-request 
  (site/init
   (slurp "test/blip/test-query.graphql")
   {:endpoint "http://localhost:2021"}))

(site-request "query-entity" {:id "entity-id"}) ;; no token header

[l4e21]

 (require '[blip.site :as site])

(def site-request 
   (site/init
       {:endpoint "http://localhost:2021"
        :auth-path "/_site/token" ;; optional
        :auth-basic {:user "admin" :pass "admin"} ;; optional, defaults to admin:admin
        :query-path "/questionnaire/query" ;; Either a string containing the slurped query file or a path on the endpoint
        :post-path "/questionnaire/graphql" ;; So blip knows where to post the queries
        })) 

 (site-request "query-entity" {:id "entity-id"}) 

This would be necessary because

1. we often fetch the query file from a path on the endpoint outside of credo-schema (they should be able to provide either a string or a path on the endpoint) If we are wrapping site there's no reason not to assume this query file already exists somewhere in site, and they don't need to provide it locally
2. Blip needs to know where to actually post the queries- in our case it is /questionnaire/graphql but if it's not there then that's an issue for other users and they need to be able to specify their endpoint path
3. the authentication path is required for site to know where to authenticate and the details to get the token.

Note that points 1 and 2 are also applicable to the general case (unwrapped)

[reborg]

As far as it stays all in the Site namespace case, looking good to me to delegate more down to Blip. I wouldn't touch the unwrapped.

[l4e21]

As far as it stays all in the Site namespace case, looking good to me to delegate more down to Blip. I wouldn't touch the unwrapped.

That should be fine provided the user knows to give the entire endpoint including the path and not just the host

[reborg]

Long term. Some interesting aspects to consider in this similar library: https://github.com/retro/graphql-builder