Extend an External Entity with Apollo Federation
Entities are types that can be extended and resolved by external federated services. This allows for a separation of concerns among our federated services. This means that one service can extend the types that are owned by a completely separate service.
Instructor: [0:00] All of the data for trails is owned by the trail service. This array contains a list of all of the trails. Notice that each trail has an ID. This unique ID can be used as a reference in other services.
[0:15] For instance, if we take a look at the data owned by the lift service, we see a different array of data. These are lifts. The lift data contains a trail field that references the trails that are accessed from that lift.
[0:29] Let's say we wanted to add a lift access field to this query. We would need to return the lift types that access this trail. The lift service should implement this field because it owns the data that associates trails to lifts. Now in order to accomplish this, we're going to need to expose the trail type to other federated services by creating a trail entity.
[0:51] From the trail service, where the trail type is hosted, we'll add a key directive to this type. Inside of this directive, we will define the key field as ID. This makes the trail type extendable by other federated services. It defines the value that these services should use when saving references to trails. That value is the trail ID.
[1:15] Now that we have a trail entity, we can extend it from the lift service. This tells the gateway to add a field called lift access to trails that resolves to a list of lift types. The reference is the ID.
[1:36] We also have to define that here when we extend the type with a key directive. We need to define the ID field in this extension as well, and we should also mark it as external with the external directive. This means that this field is external to this service but it will be available when we need it here locally in the resolver.
[1:57] Now all we have to do is add a resolver for the lift access field under the trail type. When this field is requested, the parent will be the trail. This parent object only contains a reference to the trail, the ID.
[2:11] That's enough data for me to use to filter the lift array to only those lifts that are accessed by this trail. I'll call lift.filter and this callback right here will be invoked with each lift.
[2:25] We'll check the trails array on each lift to see if it includes a reference to the current trail object -- the trail that's being resolved and the all trails query. Because we've added a new entity, we'll need to restart the gateway.
[2:39] We can see here that we have just successfully extended the trail entity from the lift service. Let's take a quick look at the query plan that was executed by the gateway. Notice this time the plan is executed in sequence as opposed to parallel.
[2:54] This means that, first, the all trails query is sent to the trail service. Even though we didn't ask for it in the current query, the ID field is also requested from the trail service because it is the key to the trail entity.
[3:07] After the trails are resolved by the trail service, another request is sent to the lift service where the lift access field is resolved. The gateway knows how to link all of the trails to this resolver by the trail ID reference.
[3:22] Finally, all of the data is flattened and combined into the single data response that we see here.