GraphQL Interface

[wilkerlucio]

For a long time, there is been conversations here and there about some way to provide a GraphQL API interface, leveraged by Pathom.

I'm creating this page to concentrate on the current ideas so people willing to work on them can find them in a single place.

A big challenge for this feature is to decide what the GraphQL API looks like, given the dynamic nature of Pathom, many different API shapes could be considered valid. To constrain that to a sane GraphQL API, I believe there is a need for some manual intervention, some configuration to decide how to shape out the GraphQL from a Pathom one.

Compatible with Pathom 2, there is the library Graffiti that uses Lacinia to make a bridge between Pathom and GraphQL. I think this is a good interface, and Lacinia is a good idea, so they do a lot of GraphQL hard parts.

This is what I have now, everybody is welcome to join the discussion here.

[jmayaalv]

I've started to look at this and wanted to share some thoughts.

In general i agree we should follow a similar idea that Graffiti used. We should continue to use specs to generate a Lacinia schema.

1. Schema Generation: Instead of trying to implement additional tooling for spec we could use Spec-tools. I think it provides must of the functionality needed to create a complete Lacinia schema including the posibility to generate the schema from the specs Spec Tools - Visitor. A similar approach is used by Leona.
2. Queries: Maybe we could also use spec to define the parameters for the grapqhl operations. Using the pathom index we could then determine if a Graphql query arg is part of the graph or an external parameter and then determine an ident or initial data for the pathom query.

Ex:

(s/def ::id int?)
(s/def ::operational boolean?)

(s/def ::droid (s/keys :req [::id ::name]
                       :opt [::operational]))

(s/def ::droid-query (s/keys :req [::id]
                             :opt [::operational]))

(pco/defresolver droid-resolver [env {::keys[id]}]
    (when (get (pco/params env) ::operational)
       {::name "a name" ::operational? true}))

{:lacinia/query 
   {::droid-query ::droid}}

With some help from the pathom index we could identify from the droid-query spec that ::id is the ident for a resolver. so an eql query could be inferred like this:

{ droid (id: 1, operational: true) { name }} ;; graphql query

[({::droid 1} [name] {::operational true})] ;;inferred eql query

Not sure how complicated this could become with more complex queries. In the worst case we could follow a similar idea as graffiti were the programmer had to manually specify input and args. ex:

{:lacinia/query 
   {::droid-query {:type ::droid 
                   :input [::id] 
                   :params [::operational]}}}

3. Mutations: They are quiet similar in both pathom and lacinia so i don't see a lot of complications here.

[jmayaalv]

Following the idea above to use spec-tools to add metadata to specs, we could create a lacinia schema similar to this one using something like:

(s/def ::episode #{:newhope :empire :jedi})
(s/def ::id string?)
(s/def ::appears-in (s/coll-of ::episode))
(s/def ::friends (s/coll-of ::character))
(s/def ::primary-function (s/coll-of string?))
(s/def ::home-planet string?)
(s/def ::character (s/keys :req-un [::id ::name ::appears-in ::episode]))
(s/def ::droid (s/merge ::character (s/keys :req-un [::primary-function] )))
(s/def ::human (s/merge ::character (s/keys :req-un [::home-planet] )))
(s/def ::hero-args (s/keys :req-un [::episode]))
(s/def ::human-args (s/keys :req-un [::id]))
(s/def ::droid-args (s/keys :req-un [::id]))


(def episode (st/spec ::episode {:graphql/description "The episodes of the original Star Wars trilogy."}))
(def character (st/spec ::character))
(def droid (st/spec ::droid {:graphql/implements ::character}))
(def human (st/spec ::human {:graphql/implements ::character}))
(def hero-query (st/spec ::hero-args {:graphql/type  ::character}))
(def human-query (st/spec ::human-args {:graphql/type (s/nilable human)}))
(def droid-query  (st/spec ::droid-args {:graphql/type (s/nilable droid)}))

;; lacinia/schema is a function that uses spec-tools visitors to generate the lacinia schema
(def schema (lacinia/schema #:graphql{:enums      [episode]
                                      :interfaces [character]
                                      :objects    [droid human]
                                      :queries    [hero-query  human-query droid-query]}))

[wilkerlucio]

I think it's a good idea to avoid tying anything to a specific library (spec in this case). I don't have anything concrete in mind at this point, but I imagine an extended version of what Lacinia uses to define the schema (so we can point to the Pathom names inside of it).

This way, later we could have something that translates from spec to it, but without requiring spec.

[jmayaalv]

I've managed to progress a bit on this based on the recommendation from @wilkerlucio. I extended the lacinia schema with a couple of keys that help to build a generic lacinia resolver that uses pathom to resolve the queries. In general, the idea is to use extra keys to map object attributes to pathom attributes falling back to defaults.

Ex:
Given the object

{:BoardGame
{:description "A physical or virtual board game."
   :fields
   {:id             {:type (non-null ID)}
    :name           {:type (non-null String)} ;;  <-----  pathom attribute infered to :board-game/id
    :rating_summary {:type    (non-null :GameRatingSummary)
                     :pathom/attribute :board-game/summary ;;;;  <----- eql queries would use this attr
   }
    :summary        {:type        String
                     :description "A one-line summary of the game."}
    :description    {:type        String
                     :description "A long-form description of the game."}
    :designers      {:type        (non-null (list :Designer))
                     :description "Designers who contributed to the game."}
    :min_players    {:type        Int
                     :description "The minimum number of players the game supports."}
    :max_players    {:type        Int
                     :description "The maximum number of players the game supports."}
    :play_time      {:type        Int
                     :description "Play time, in minutes, for a typical game."}}}}

Additionally i was thinking it would be useful to add pathom/namespace to the object itself and then all attributes of the object would use that as default if no attribute is defined.

{:BoardGame
{:pathom/namespace :com.board-game ;; <--- default namespace for the object
:description "A physical or virtual board game."
 ...}}

The lacinia resolvers are resolved by the same fn:pathom/resolver, a generic resolver that analyzes the grapqhl query and uses pathom. ex:

:game_by_id
  {:type        :BoardGame
   :description "Select a BoardGame by its unique id, if it exists."
   :args
   {:id {:type (non-null ID)}}
   :resolve     :pathom/resolver}

So far very simple queries can be processed, ex:

{ game_by_id (id: \"1236\") { id name }}

I have pushed my progress here https://github.com/jmayaalv/graffito The name is not very original but maybe a good tribute to graffiti? :/

[cyppan]

I'm working on this (a Lacinia schema powered by Pathom) and want to share my vision too: I agree with you guys about the GraphQL object parts, the dynamic nature of Pathom can't (shouldn't?) address this. So I'll consider GraphQL schema objects and GraphQL queries as separate problems. I didn't even consider mutations and subscriptions yet.

GraphQL objects

We are heavy Prismatic schema users at BeOp so I've worked on a simple prismatic-schema->graphql-objects to declare the GraphQL schema objects easily, there are some caveats resolving properly the GraphQL scalar types from the schema though, but it works™️.

GraphQL queries

I've chosen to declare the queries explicitly, it helps controlling and documenting what part of the Pathom graph becomes a valid entry point for consumers.
And in each query resolver, I simply convert the incoming graphQL query with args into valid Pathom EQL with params, it's actually pretty straightforward to do at first sight.
What I still have to figure out is how to parallelize queries resolution when multiple are provided in the same request.

I'm thinking now about what's the best way to declare and feed "joins" in the schema from Pathom, (in GraphQL can be seen as the relations between objects, for instance a list of addresses for a given user). I also plan to make this explicit, probably by adding fields in the GraphQL objects with the same name as the Pathom resolvers output, to leverage the root query resolver also (I want to keep Pathom as the fetching orchestrator).

Not sure it's very clear 😅 I'll try to share some code soon.

[souenzzo]

I started doing a direct translate from the GraphQL AST (Lacinia provides it) to EQL Queries.

this appeared a promising idea.

It would allow you to given a request with a GraphQL query, it turns into a EQL Query, runs on pathom and return the value.

But deliver a GraphQL API without a schema will make most of the GraphQL users freakout.

I thought in some ideas like

• Manually write a schema
• generate a schema from pathom index

https://github.com/souenzzo/eql-gql

[wilkerlucio]

I think removing the GraphQL introspection would be a problem, this is an important and expected feature from users.

So far the approach from @jmayaalv seems the most promising IMO. Extending the Lacinia schema to make the connections to the Pathom underneath.

[cyppan]

Update: (sorry it might be a bit off-topic, let me know)
We are trying currently another way than having a GraphQL server on top of Pathom (which is, whatever the approach, a lot of additional work). We would have been happy to use EQL directly from the front, but EQL is hard if you're not in the Clojure eco-system (1).
There is the solution to use AST directly, but well... it's not very nice to declare your queries that way.

So instead, I've thought about a small DSL, which is a bit more verbose but translates easily to EQL (or AST of course), and is more JSON-compliant (map keys are always strings, never composite).

Ex: on the front side (2)

["account/name",
 {"key": "account/default_settings.location_expanded", 
  "pathom/as": "account/default_settings.location", 
  "query": ["location/name", "'*"]}]

is mapped back-side into

[:account/name
 {'(:account/default_settings.location_expanded {:pathom/as :account/default_settings.location})
  [:location/name '*]]

And would result in (3)

{"name": "my account",
 "default_settings": {"location": {"name": "..."}}}

Notes:
(1) our current front is written in ReScript and use a JSON Rest API to communicate with our Clojure backend
(2) the dots in the keyword names might look odd, but it's very useful to transform automatically a flat Pathom output into a nested one (which is the one we use front-side)
(3) we remove all the namespaces from the output, they are only used in the Pathom graph (so they're needed in the queries)

[jmayaalv]

Most of the ideas we have discussed here are now available Graffito

Hopefully an initial announcement could bring more interested people to work on the ideas discussed here.

Cheers