Too often it seems the thinking is, “🤔 We want separate services, we’ll figure out our API contract along the way”. Graphiti approaches from the opposite angle - figure out the API contract, and you get separate services as a side-effect 😃💡
Resources have a defined query contract, and connect together with Links. Put two and two together, and you’ll see a Resource doesn’t need to be local to a single application. We can have Remote Resources as well:
You might want separate applications that are independently deployable, or you might want to break apart that slow test suite. The draw of isolated services is clear. Though you should be aware of the tradeoffs when breaking apart a Majestic Monolith, Graphiti helps you lessen those tradeoffs.
The most common service problem I see is a breakdown in cross-service communication:
- 🚫 No consistent or flexible query interface
- 🚫 No consistent error handling
- 🚫 No clear patterns on when and why to separate services
- 🚫 No types or backwards-compatibility checks (unless GraphQL)
- 🚫 A fair amount of glue code required
Graphiti was built from the ground up to address all these points. We have a defined query contract, errors payload, a schema with types and backwards-compatibility checks, and organize code into RESTful Resources. Not only can we facilitate cross-service communication, we can automate it.
Note: Remote Resources are for read operations only. The exception is associating to an existing
Note: We use Faraday to hit the remote API. You must add
faradayto your Gemfile to enable remote resources.
How it Works
Let’s take a simple association:
This would generate a Link for lazy-loading comments:
Critically, those same lazy-loading parameters are used when eager-loading:
OK, and we also know Resources support any backend, and we can build an Adapter if our backend supports common operations like filtering, sorting, and pagination.
So, that means we can build an Adapter that makes an HTTP request to another Graphiti Resource that lives in a separate API. That adapter is built into Graphiti and comes out-of-the-box:
This Resource works as normal. We can execute queries:
And we can sideload just like we always do:
We’ll still support Deep Querying - let’s fetch the Post and its
active comments, ordered by
CommentResource has an association to
AuthorResource is defined in the remote API, we can fetch it as
normal - no special configuration needed to fetch the
Authors in a single request.
But maybe only
CommentResource is remote, and
Authors are local.
We need only define the association locally:
Let’s say we need to tweak the display of a property coming from the remote API. Again, works just like normal:
You only need to define attributes when overriding this logic - otherwise we’ll take them directly from the API response. This means you don’t have to update two repos and coordinate deploys - as soon as you add a property to the remote API and deploy it, it will be reflected in the local API response.
For the typical use case, we don’t even need to create this Resource
class. The sideload definition accepts a
remote: option, which will
create a Remote Resource under-the-hood:
NOTE: When sending a request to a remote API, we request page size
999so results don’t get accidentally cut off. If you need successive requests, please submit an issue.
We use Faraday under-the-hood, which allows for various adapters and middleware. In addition:
By default we’re going to forward the
Authorization header of the request to the remote API. To override the default headers sent:
If the remote API has an error, we want to re-raise that same error. But unless you’ve enabled displaying raw errors, we won’t be able to - the only information we have is what’s returned from the API.
You’re encouraged to display raw errors when an internal or privileged user:
If you do this, we’ll be able to re-raise the original error, including stacktrace. If raw errors are not enabled, we’ll raise whatever information is given.
Both styles will be wrapped in
Graphiti::Errors::Remote, so you can
differentiate between a local error and a remote one.
When testing a remote resource, we need to mock the API request and
response. Graphiti gives you a spec helper to do just that -
include_context "remote api":
This shows all the pieces needed to test remote APIs. We want to test
- The correct URL is hit
- When given a valid response, the rest of the flow works as expected.
NOTE: if the remote relationship is a has_many, the API will need to return the foreign key as part of the response. Otherwise, we won’t know how to associate these children to their parents.
Here’s a slightly longer version, showing that
Post can sideload
Make sure to include
page[size]=999in the test URL!