`?include=...` query param

[amaury1093]

On the frontend, I need the territories, and their related PoliticalEntity's color.

@whirish proposed to return the color for requests on /territories. I solves my immediate problem, but it's not really future-proof.

Proposal:

• /territories?include=politicalentity, cf https://jsonapi.org/format/#fetching-includes

Notes:

• Other query params can also be added, like partial resources, i.e. ?fields=... to only return relevant fields, https://developers.google.com/tasks/performance#partial-response.
• The idea is to create a basic query language with query params. GraphQL would solve the problem, but we decided not to go that route.

[dwaxe]

I would recommend against the include pattern, even with the additional fields parameter. It has the danger of leading to large amounts of data duplication in the response object, e.g.

{
  {name: vichy, politicalentity: {name: france, color: blue, references: ["https://en.wikipedia.org/wiki/France"]}, ...},
  {name: gaul, politicalentity: {name: france, color: blue, references: ["https://en.wikipedia.org/wiki/France"]}, ...},
  {name: ile de france, politicalentity: {name: france, color: blue, references: ["https://en.wikipedia.org/wiki/France"]}, ...},
  ...
}

I suggest instead going with @whirish's initial suggestion of adding the color to the TerritorySerializer, i.e. CharField(source='entity.color'), and implementing future desired fields on an individual basis so we can keep our responses relatively clean and efficient.

I do support adding the fields parameter to allow the frontend to filter the serializer down to relevant fields. Something like what's in the documentation here (https://www.django-rest-framework.org/api-guide/serializers/#example)

[amaury1093]

@dwaxe: Thinking long-term, I see 2 problems. Both are imaginary scenarios, that's why this is a proposal for future-proofing.

1. Let's say the frontend really needs the nation's name+color+references, e.g. to show a marker popup on the map on the territory (quite plausible, depending on the design). Your solution does not solve the data duplication problem.

2. Imagine there are 2 places where the frontend hits the /api/territories endpoint, one with colors, the other without. How do you differentiate them? Add ?with_colors=true and other custom query params?

---

To avoid over-data-fetching, we can follow graphql's whitelist approach: the frontend needs to provide a ?fields=... query param to get something back.

[dwaxe]

In the case of 1, I think the frontend should make a request to api/politicalentities/<id> to get nation specific data.

For 2, I think I misunderstood your initial recommendation with includes. I was imagining expand, returning the entire nested object, which is the antipattern I described in my example above.

I second your suggestion for a fields parameter.

[quorth0n]

I'm fine with this 👍 . If we wanted to we could also wrap the API in gql as described here.