Linking Entities - REST

[LGRmac]

This is a multi part question that all relates to the same topic - I want to be able to Link Entities through a REST API - using the swapi as an example. I have been following this documentation: https://graphweaver.com/docs/linking-entities
I will be linking a Vehicle (or many Vehicles) Entity to a Person Entity.

I can link a single entity by creating a field in Person called vehicle_id and hardcoding it in the People.ts schema file. However, I cannot assign it programmatically, as not every person has a vehicle, and thus there is an error Cannot return null for non-nullable field Person.veh. Even if the field is assigned a blank string.

//Entities people.ts
@Field()
vehicle_id: string;

@ExternalIdField({ from: 'Vehicle' })
veh: Vehicle;

//Schema File people.ts
@RelationshipField<RestPerson>(() => Vehicle, { id: 'vehicle_id' })
veh: Vehicle;

Assigning multiple Entities does not work either as the GraphQL query turns up blank.

//Entities people.ts
@Field(() => [String])
vehicle_ids?: string[];

@ExternalIdField({ from: 'Vehicle' })
v: Vehicle[];

//Schema File people.ts
@RelationshipField<RestPerson>(() => [Vehicle], { relatedField: 'vehicle_ids' })
v: Vehicle[];

  {
    name: 'Grievous',
    height: '216',
    mass: '159',
    hair_color: 'none',
    skin_color: 'brown, white',
    eye_color: 'green, yellow',
    birth_year: 'unknown',
    gender: 'male',
    homeworld: 'https://swapi.info/api/planets/59',
    films: [ 'https://swapi.info/api/films/6' ],
    species: [ 'https://swapi.info/api/species/36' ],
    vehicles: [ 'https://swapi.info/api/vehicles/60' ],
    starships: [ 'https://swapi.info/api/starships/74' ],
    created: '2014-12-20T19:43:53.348000Z',
    edited: '2014-12-20T21:17:50.488000Z',
    url: 'https://swapi.info/api/people/79',
    id: '79',
    vehicle_id: '60',
    vehicle_ids: [ '60' ]
  },

There is also some confusion around the use of id and relatedField.
If the Vehicle Entity has an id field and a vh_id field, and the Person Entity has a vehicle_id field, how would I use these id and relatedField properties to force GraphWeaver to join vehicle_id (person) to vh_id (vehicle)?

As It would appear, relatedField: 'vehicle_id' only joins vehicle_id (from the person entity) to id (of the vehicle entity)

//person
{
    name: 'Grievous',
    vehicle_id: 60,
    id: 79
}

//vehicle
{
    name: 'Snowspeeder',
    vd_id: 100,
    id: 14
}

Another thing I noticed is that GraphWeaver is calling the Vehicle Entity for each Person. That is; if I hardcode each person (say 83 people) to have a single vehicle (the Snowspeeder with id:14), the fetch function from the Vehicle Entity schema file, is called 165 times. Is this intended behaviour? If not, how do we write the linked entities such that their information is only fetched when required - i.e. a REST call that uses parameters, such as the vehicle ID?

export const fetchVehicle = async <T>(path: string) =>
	got.get(`https://swapi.info/api/vehicles/${path}`).json<T[]>();

Questions:

1. Where have I gone wrong linking a single Entity programmatically? How do we achieve this?
2. How do we link multiple entities programmatically?
3. How do we correctly use the id and relatedField properties?
4. How do we modify the REST API calls to prevent over fetching - under the hood - when linking entities?

[thekevinbrown]

Hey there, sorry for the slow response. I'll answer below:

First off you'll want to always only have one property with a given name. In your example you've got two veh properties, so that'll cause some issues. We'll often do something like vehicle_id is the @ExternalId, then vehicle is the relationship field.

Here are the answers to your specific questions:

1. It looks like all you need to do here is mark the relationship as nullable, e.g. @RelationshipField<RestPerson>(() => Vehicle, { id: 'vehicle_id', nullable: true })
2. The two ways to join with a RelationshipField are dependent on who has the foreign key. If you're on the side that has the foreign key, (so in your example, Person, because it has the vehicle_id field) then you should use id to join. If you're on the non-owning side, (Vehicle in your example), then you use relatedField to tell Graphweaver what the foreign key is.
3. Another note, @ExternalId is for when you want to join across datasources, so if you have database records that reference the REST entities, you'll want to use that on the foreign keys you store that cross the boundary.
4. Standard REST doesn't have a way to do complex filtering, or fetch where ID is in a specific set. The only choices we have are to paginate all results, then do the filtering in memory (which will stop working at a certain size) or to individually load the entities from their /id endpoint. Individual loads are the default, but if your API supports complex filters where you can pass an array of, say, 100 IDs and load those, we can use DataLoader for this purpose, and that's how we load nested entities for databases and OData. Given that you're using the Star Wars API, that particular API doesn't have this option. I'll say several things about this behaviour:

• You should only see it do this if you actually request the relationship data in the query. The admin area does this by default, but you can hide properties in the table in the Admin Area if you don't want to make your API do the work just for admin users.
• We find usually it's ok to just go get the data when you need even if it looks a bit over the top. APIs are quite quick these days. If that simply doesn't work in your use case, you can investigate providing a multi-fetch endpoint in the REST API which we can then use with a DataLoader approach, you can implement caching for the REST entities using something like Redis, or as a last result, you can sync the data to a database where it can then be properly filtered. It's very rare that we have to fall back to syncing though with the other strategies at our disposal but all the options are on the table.