I'm just gonna say I wish this guy (Rich himself) records the talk he performed at our local Ruby meetup last week.
As important as a GraphQL alternative is at face value, he explained quite elegantly how he and his coworkers came to this solution. I do insist, like I did in person, that as a frustrated GraphQL noobie and fumbler with Prisma, I'm super glad to see alternative tools and mindsets and will being try it as soon as I have time for personal tinkering.
Even if hypothetically I didn't choose this with a clean slate over more popular GraphQL tools, he did a great job at placing deep technical architecture choices in the context of his philosophy and experience, Ruby and otherwise. Spraypaint also seems cool.
I don't want to spend 5 minutes getting a feel for it (first link on the page) before I have some clue what it is or whether I care.
Putting one sentence of what Graphiti is on the actual homepage would help adoption enormously. "Graphiti makes RESTful Resources a first-class concept" doesn't count as an explanation of what Graphiti is. "This enables reading and writing a graph of data in a single request, a schema with backwards-compatible gaurantee, end-to-end integration test patterns, seamless microservices and much more" might be a great explanation for the developer who wrote Graphiti but doesn't ease me as a first time visitor to the site into a comfortable understanding of whether Graphiti will solve my problem.
> might be a great explanation for the developer who wrote Graphiti but doesn't ease me as a first time visitor to the site into a comfortable understanding of whether Graphiti will solve my problem
I hear you. This project is vast, and distilling to a meaningful sentence has been challenging. I will continue trying to refine this, but in the meantime the first 60s of this video should give a sense of what we're about https://youtu.be/_QqXjZDzTf4
Doesn't help that the word "graph" can mean multiple things, from a visual representation to a mathematical abstraction to... well, whatever it means in the context of REST.
Great resource. Looked at it a long time ago and now it seems so much more developed. For those trying to understand how this works I'd recommend the quickstart, https://www.graphiti.dev/quickstart. It took me 5" to read it and understand where Graphiti stands. If you are a Rails developer this breaths a lot of fresh air and it seems to deliver on a lot of great features. I've been thinking about digging more into GraphQL but this seems to give me enough hope that REST might still de3liver once more.
Not saying this has to exactly replace graphqL, but I'm struggling to understand the advantages and disadvantages over REST and GraphQL, or even how it tackles the problems graphQL is trying to solve.
It looks more like an ORM querying over rest than it is graphQL. It doesn't appear to solve some or the 2 major headaches graphQL is great at solving:
* clients choosing how much data they need. On a desktop on broadband client, I want details of a list of entities, while on a mobile app with limited screen space and less bandwidth, I just need the skinny details like title and summary.
* pooling requests to multiple domains into a single request. For example, if I writing a reservations endpoint, for purchasing flights. I need to call 3 separate microservices, 1 for availability and booking, 1 for ecommerce that's hooked up to an accounting system, and one for trip details from say a CMS system. I don't see how this saves the client the burden of making all these separate requests. In rest, you probably will have 1 endpoint that combines these requests, and separate endpoints for accessing this information individually. GraphQL saves the burden of maintaining separate combination endpoints.
> It doesn't appear to solve some or the 2 major headaches graphQL is great at solving: * clients choosing how much data they need. On a desktop on broadband client, I want details of a list of entities, while on a mobile app with limited screen space and less bandwidth, I just need the skinny details like title and summary.
JSON:API solves this problem through sparse fieldsets[1]. Graphiti clarifies the spec by allowing sparse fieldsets at any level of nesting. As the original author and a current editor of the spec, I think we should adopt this extension into the spec proper.
> * pooling requests to multiple domains into a single request
JSON:API operates against a logical "graph in the sky", just like GraphQL. Graphiti makes it possible to mix and match database queries with other services and even plain Ruby objects[2].
One nice thing about this approach is that you still get to make database queries that take advantage of indexes and other database optimizations organically and by default. GraphQL's field-based approach can often result in a lot of extraneous database queries in the service of a homogenous server API that is based on fields.
(In my experience working with GraphQL APIs, I've seen a lot of performance issues that could only be debugged as "why is this field slow" that could have benefited a lot from making a big chunk of the query against a SQL database, directly using decades of optimizations around query planning).
> I'm struggling to understand the advantages and disadvantages over REST and GraphQL
The "Why Graphiti" page[1] goes into some of this, getting into some comparisons of REST, RPC, and GraphQL, as well as discussing the conventions that make some of Graphiti's approach possible.
I appreciate the effort. I think it is a bit of initial information overload having to read through tons of theory before getting to examples, which is why I skimmed through it and went to the examples. However the examples, did provide too much explanation and at the surface looks like a Query ORM via URL. This seems like a nice idea for things within a single domain, such as a master/detail view.
In my reservations example, if I wanted to get availability, pricing, and content from 3 separate domains in a microservice environment, using this paradigm, I think I still would have to create a 4th endpoint that that combines the 3 in a separate entity called VacationPackages if I wanted to keep separation of concerns.
Otherwise, it might be calling a CMS endpoint, which has an include of availability endpoint, which has a nested include of the pricing endpoint.
Hi Dlai - you'd be able to fetch it all, across all your microservices, without creating a new entity. Will try to improve our messaging, but this one might be up your alley https://www.graphiti.dev/guides/concepts/remote-resources
Hi dlai - you can do all this in Graphiti. The client can specify only the fields/associations it wants, you can grab everything in a single request, and than single request can fan across microservices. This video might help https://youtu.be/_QqXjZDzTf4
That video is definitely a great start. They should add that to the homepage. I was having a hard time comprehending all that in "Why Graphiti", that video explains it nicely.
I like that it's simpler and easier to reason about than GraphQL.
I like the elegant solutions for lazy vs eager loading and supporting separate endpoints.
I like the sensible defaults for filtering and sorting based on type.
This is a very well thought out project, good job. Will it be the Next Big Thing? I'm not gonna make a call either way, but I'm glad that this exists and at the very least is worth investigating when building a new project.
I’ve consulted with a project that used JSONAPI Compliable (Lee’s original project) and has since switched to Graphiti. Lee’s support of the team lead of that project via Slack is nothing short of incredible. He’s gone so far out of his way to help, refusing any form of compensation. Wish more open source devs had the extreme care for support that he does. Kudos @richmolj!
I am not familiar with graphqL and this tool looks interesting but after spending 10 minutes on the site trying to understand what it does (in layman terms) I am totally lost. Could be me or it could be the developer needs to explain it better ¯\_(ツ)_/¯
This seems be an implementation of (or heavily based on) JSON:API. Which is cool, but I think it would better if the documentation made that clear from the get go.
I've used Graphiti in a project; as it looked promising on the surface. But as my needs grew, I often found myself fighting with the DSL. It makes the easy things easy, and the hard things very painful and hard. This is a problem with any DSL heavy framework.
If you have a toy project, than try Graphiti. If you're solving real-world problems; stick with GraphQL.
Maybe it’s just me, but having used both tools; graphQL-ruby is much simpler. There isn’t much to learn with graphQL-ruby, since the graphql spec is so elegant compared to jsonapi.
Fighting with the DSL, I mean cryptic errors, no instance variables to work with, and no straight forward way to extend the framework. I know it is possible to extend the framework, but it’s not very intuitive.
To add on to this, we'd love to get specific examples of things that you find challenging or that otherwise don't work well. We've found over time that these tend to fall into either A) a missing feature, B) Missing documentation, or C) a missing concept in the domain being modeled. As we've added more features and handled the edge cases, we see more of B & C than A, but of course that happens still as well.
Ultimately, the value prop of a tool like Graphiti or GraphQL is independent of the exact details of the wire format.
Graphiti uses JSON:API[1] under the hood as its protocol, which is a language-independent protocol with a wide variety of clients[2], and is now built-in to Drupal[3].
I designed JSON:API in ~ 2013 with a narrow purpose: to describe a protocol for incrementally communicating with server-side graphs over HTTP.
By incremental, I mean the possibility of fetching exactly the data you need at first, but then slowly filling in more data over time as a user interacts with an application.
URLs are a great "internet pointer", so when I was looking for a way to link fetched data with other not-yet-fetched data, URLs were the natural answer. On the other hand, a lot of REST APIs at the time didn't have a good way to eagerly send a whole bunch of graphy data down at once.
JSON:API's concept of linkage supports both models: a type/id pair for data the client already knows about and a URL for data it doesn't. You can even combine the two, to enable incremental refreshing of a piece of data that you fetched as part of the first request (simply by hitting the URL).
JSON:API was designed to work well with many kinds of client-side approaches, including ORMs. This meant using a composite key of type/id to identify records and not just a single ID. Over time, this has become a best practice for other tools in the space[4][5]
OData exists in a similar space as JSON:API, but JSON:API is much more tightly focused on the problem of incrementally fetching a graph of data from the server into the client. Focus is good :)
I don't have a lot of context on OData, but from what I can tell from a quick look at the site, it seems a closer comparison would be the JSON:API spec https://jsonapi.org/. Graphiti took a great deal of influence from that spec, and was originally much more directly coupled to it. Now it's the default serialization format, but not the only one. It would probably be possible to "speak OData" as well if that was a big need.
This is interesting. I have felt some of the issues described on the /guides/why page when trying out GraphQL. I don't have much experience with Netflix's Falcor, but I'd be curious to know how it compares with Graphiti.
One way I remember how to spell it is to start from “warranty” which is almost the same word and much easier to spell, then replace the “w” with “gu” (in some languages they’re mostly the same sound) then replacing the “y” with “ee” isn’t so hard to remember
I don't understand what makes this "RESTful". How can something that doesn't specify the content of the resources be asserted to be RESTful? As far as I can see, Graphiti doesn't dictate that the resources contain any state.
As important as a GraphQL alternative is at face value, he explained quite elegantly how he and his coworkers came to this solution. I do insist, like I did in person, that as a frustrated GraphQL noobie and fumbler with Prisma, I'm super glad to see alternative tools and mindsets and will being try it as soon as I have time for personal tinkering.
Even if hypothetically I didn't choose this with a clean slate over more popular GraphQL tools, he did a great job at placing deep technical architecture choices in the context of his philosophy and experience, Ruby and otherwise. Spraypaint also seems cool.
A pleasure to see you on HN, man.