Smokescreen 3 Planning

[ababkov]

Key issues with current version

• Difficulty of understanding core code base
• Deep introspection not possible with current structure.
  • Query optimization and nested eager loading is difficult (N+1)
  • Pagination (or first page retrieval) of subsets not possible (Excess data is loaded)
  • Documentation can't be generated for available fields or includes (Keeping docs up to date manually is difficult)
  • Cost calculation - how much will the query cost to allow for sophisticated API rate limiting
• Sparse fieldsets vs includes - current behaviour of not distinguishing between the two can lead to issues, doesn't throw errors etc.
• We like REST but need to be able to support graphql for the clients that are sophisticated enough to utilise it and especially for ourselves (otherwise types are maintained in two locations)
• Performance is unclear - we need sophisticated benchmarking (especially around query volume)
• Split between this package + the smokescreen laravel package seems potentially unnecessary - that's not to say that this package shouldn't offer laravel specific drivers etc and / or be able to work without laravel, just that maintaining two repos is painful. The alternative might be two packages with a mono repo approach.

Possible solutions

A lot of what we're after relates to introspection and meaningful types.

Some key projects for inspiration and in some cases possbile dependencies:

• Type System:
  • https://webonyx.github.io/graphql-php/type-system/ - GraphQL Type System - https://github.com/webonyx/graphql-php - we could also write / wrappers / adapters for our native Enum + DTO types
• Deferred Loading aka Batch Loading:
  • https://webonyx.github.io/graphql-php/data-fetching/ (See the Solving N+1 Problem section)
  • https://github.com/graphql/dataloader - An open source port of facebooks original loading approach
  • https://github.com/overblog/dataloader-php - A php based implementation of the above
• Laravel implementations
  • https://github.com/rebing/graphql-laravel
  • https://lighthouse-php.com/
• Query complexity + cost:
  • https://webonyx.github.io/graphql-php/security/#query-complexity-analysis

Why Not just GraphQL

Our favourite part of GraphQL are the types and the data loading mechanisms that the type resolution system affords.

• B2B consumers and server to server consumers in our experience are still extremely heavily biased towards REST
• GraphQL's mutation approach is not particularly good - the semantics that rest verbs and url structures carry simplifies things significantly
• GraphQL still carries a fair bit of complexity - if we can, our preference is to hide some of that complexity at the cost of losing some functionality we aren't necessarily that interested in.
• Post for everything is not great - sparse fields are optional, we should be able to cache if we want to - POST prevents that.
• What can be queried and what can be loaded are potentially two quite separate concerns.