sema-graphql

Minimal GraphQL client — run queries and mutations over HTTP.

GraphQL is one endpoint and one verb (POST): every request sends {query, variables, operationName} and gets back a {data, errors} envelope. This package wraps that so you get :data directly and a clear error when the server reports GraphQL errors. Auth is whatever headers the API needs — pass them to the client.

Install

sema pkg add sema-graphql

Quick start

(import "sema-graphql")

(define gh (graphql/client "https://api.github.com/graphql"
             {:headers {:authorization (str "Bearer " (env "GITHUB_TOKEN"))}}))

(graphql/query gh "query($login:String!){ user(login:$login){ name } }"
               {:login "torvalds"})
; => {:user {:name "Linus Torvalds"}}

API

graphql/client

(graphql/client "https://api.example.com/graphql")
(graphql/client "https://api.example.com/graphql"
  {:headers {:authorization "Bearer tok" :x-api-key "..."}
   :timeout 15000})

Returns a client map {:url :headers :timeout}. :headers carries auth (the form varies per API); :timeout defaults to 30000 ms.

graphql/execute / graphql/query / graphql/mutate

;; a query with variables
(graphql/query client
  "query($id:ID!){ node(id:$id){ id } }"
  {:id "abc"})

;; a mutation
(graphql/mutate client
  "mutation($t:String!){ createTodo(title:$t){ id } }"
  {:t "ship it"})

Returns the response :data map. If the response carries GraphQL errors, it raises graphql: <endpoint> — <joined error messages>. The optional 3rd arg is the variables map; the optional 4th is an opts map with :operation-name (for documents that define more than one operation).

graphql/request

(graphql/request client {:query "{ me { id } }" :variables {}})
; => {:data {:me {:id "1"}}}          ; or {:data ... :errors [...]} for partial data

The raw escape hatch: returns the whole {data, errors} envelope without raising on GraphQL errors (it still raises on transport/non-2xx errors). Use it when you want partial data alongside errors.

Testing

sema pkg add sema-test   # once
sema tests.sema
# live test against a public API: SEMA_LIVE_TESTS=1 sema tests.sema

License

MIT