Repository files navigation

sangria-federated is a library that allows sangria users to implement services that adhere toApollo's Federation Specification, and can be used as part of a federated data graph.

SBT Configuration:

libraryDependencies+="org.sangria-graphql"%%"sangria-federated"%"<latest version>"

The library addsApollo's Federation Specification on top of the provided sangria graphql schema.

To make it possible to use_Any as a scalar, the library upgrades the used marshaller.

A good example showing all different features is thesangria implementation of the Apollo Federation Subgraph Compatibility.

All the code of this example is availablehere.

To be able to communicate withApollo's federation gateway, the graphql sangria service should be using both the federated schema and unmarshaller.

As an example, let's consider the following services:

• areview service provides a subgraph for review
• astate service provides a subgraph for states. This state is used by reviews.
• both subgraphs are composed intoone supergraph that is the only graph exposed to users. With that, users can interact with reviews and states as if they were implemented in one service.

The state service defines the state entity annotated with@key("id").

For each entity, we need to define anentity resolver.

It's highly recommended to useDeferred Value Resolution in those resolvers to batch the fetching of the entities.

Implementation of the State GraphQL API.

The entity resolver implements:

• the deserialization of the fields in_Any object to the EntityArg.
• how to fetch the proper Entity (in our caseState) based on the EntityArg.

In the definition of the GraphQL server, we federate the Query type and the unmarshaller while supplying the entity resolvers.Then, we use both the federated schema and unmarshaller as arguments for the server:

defgraphQL[F[_]:Async]:GraphQL[F,StateService]= {val (schema, um)=Federation.federate[StateService,Any,Json](Schema(StateAPI.Query),    sangria.marshalling.circe.CirceInputUnmarshaller,    stateResolver)GraphQL(schema,DeferredResolver.fetchers(StateGraphQLSchema.states), ctx.pure[F])(Async[F], um)}

ThestateResolver delegates the resolution of the state entities to aFetcher,allowing the state service to resolve the state entities based on the provided ids in one batch.

The GraphQL server uses the provided schema and unmarshaller as arguments for the sangria executor:implementation

• The review service defines theReview type, which has a reference to theState type.

  implementation of Review GraphQL API

• AsState is implemented by the state service, we don't need to implement the whole state in the review service.Instead, for each entity implemented by another service, astub type should be created (containing just the minimal information that will allow to reference the entity).

  implementation of the stub type State(notice the usage of the @external directive).

• In the end, the same code used to federate the state service is used to federate the review service.

Thefederation router can expose the GraphQL endpoint, and resolve any GraphQL query using our sangria GraphQL services.

The sangria GraphQL services endpoints are configured in thesupergraph configuration, used by rover to compose the supergraph:

federation_version: 2subgraphs:  state:    schema:      subgraph_url: http://localhost:9081/api/graphql  review:    schema:      subgraph_url: http://localhost:9082/api/graphql

• This is a technology preview. We are actively working on it and cannot promise a stable API yet.
• It's highly recommended to useDeferred Value Resolution in theEntityResolver to batch the fetching of the entities.
• The library upgrades the marshaller to map values scalars (e.g. json objects as scalars). This can lead to security issues as discussedhere.

Contributions are warmly desired 🤗. Please follow the standard process of forking the repo and making PRs 🤓

sangria-federated is licensed underApache License, Version 2.0.