Strategies for API hierarchies

We can apply different ideas to set-up a hierarchy for our API endpoints.

Query first, override schema permalink

We can define the parent to contain a common GraphQL query, and then extend it for each of the different applications.

For instance, the parent persisted query /graphql-query/posts/ will define the GraphQL query:

query GetPosts {
posts {
id
title
url
}
}

And the child persisted queries, for the website and the mobile app, will set the corresponding schema configuration:

  • /graphql-query/posts/website/ => use schema configuration "Website"
  • /graphql-query/posts/mobile-app/ => use schema configuration "Mobile app"

Schema first, override query permalink

Alternatively, we can declare the schema configuration at the parent level, and then all children inherit it, and implement only the GraphQL query:

  • /graphql-query/mobile-app/posts/
  • /graphql-query/mobile-app/users/
  • /graphql-query/website/posts/
  • /graphql-query/website/users/

Translate endpoint permalink

Translate the content in an endpoint by providing the language code via a variable, which can be overriden by the child endpoint.

For instance, we can create a persisted query /graphql-query/posts/ with this GraphQL query:

query GetTranslatedPosts($lang: String!) {
posts {
title @translate(from: "en", to: $lang)
url
}
}

We don't need to execute this endpoint directly, so it can be disabled.

Then, we create child persisted query /graphql-query/posts/french/, which overrides the GraphQL variable:

{
"lang": "fr"
}