GraphQL Clients and API construction

Create sections on

• consuming graphql apis
• creating graphql apis (hasura, walmart library

Clojure as a GraphQL API client

• use http requests
  • http-kit/client
  • http-clj)
• use specific graphql client project
  • https://github.com/oliyh/re-graph
  • https://github.com/retro/graphql-builder - clojure and clojurescript
• graphql query string generation
  • https://github.com/district0x/graphql-query - Clojure and clojurescript (forked from venia clojurescript only)

Other clients

• defacto GraphQL client - https://www.apollographql.com/docs/

Clojure to create a GraphQL API

• lacinia
  • https://lacinia.readthedocs.io/en/latest/
  • https://github.com/walmartlabs/lacinia
• GraphQLize - built on top of Lacinia
  • https://www.graphqlize.org/
  • https://lacinia.readthedocs.io/en/latest/
• Visual editor
  • https://github.com/graphql-editor/graphql-editor (node.js)

Testing graphql apis

• https://blog.testproject.io/2020/06/23/testing-graphql-api/

Documentation generators

How to generate searchable documentation for a GraphQL api.

• static page generators
  • https://github.com/2fd/graphdoc

Ideally the GraphQL API should be self documenting and each field description is exposed when browsing the graph using a graphql client. An example of how a graph can be self documenting: hasura uses field descriptions from comments added to columns in the Postgresql database. In lacinia, I assume a similar thing could be done or the schema if defined in EDN could be self documenting and therefore be used to generate the field descriptions in a graphql client.

Resources to review

• https://www.juxt.pro/blog/through-the-looking-graph
• https://medium.com/@kirill.ishanov/poor-mans-graphql-client-for-clojurescript-apps-8dc4b04e8738
• https://clojureverse.org/t/querying-graphql-in-clojure/7528
• https://clojureverse.org/t/querying-graphql-in-clojure/7528
• https://www.slideshare.net/KentOhashi/graphql-api-in-clojure-129989325 - presentation: lacinia-predistal, duct, venia

Start by narrowing the proposed documentation sections around consuming and creating GraphQL APIs in Clojure, then review the listed client projects, Lacinia, GraphQLize, testing resources, and documentation generators. Done should mean the agreed scope is documented with useful examples, testing guidance, and an explanation of self-documenting schemas.