Thread by @JeffHandley

@rj_dudley In summary, OData was a way to serialize a SQL statement into a URL. When first applied, it gave too much power to the client, allowing it to use joins, where clauses, and sorting. A lot of that power can be dialed back now, but I still found it challenging to limit the exposure.

@rj_dudley By opening up an OData endpoint, you lose control of what your clients are able to do and you don't have explicit queries or use cases tracked. So when you need to change your schema, it becomes challenging to maintain backward compatibility with what your clients are doing.

@rj_dudley And it also becomes exceptionally difficult to optimize performance for any given use case because all execution runs through the same pipeline. Hooks were there to do it, but you have to process IQueryables in order to fulfill specific queries with tuned implementations.

@rj_dudley So when a client conducts a specific query and reports to you that performance is poor, you have to do really heavy lifting to address it. And in doing so, you can inadvertently disrupt other callers with similar but inexact scenarios/queries.

@rj_dudley In many ways, OData queries result in remote code execution by design. My team and I had to address this specific security bulletin where specially-crafted GET requests could employ remote code execution to take down any public OData server: docs.microsoft.com/en-us/security…

@rj_dudley Okay. So now some positives about GraphQL!

1. The server implements resolvers that fulfill specific graph queries—the client cannot ask for anything the server does not explicitly handle.

@rj_dudley 2. The server returns only what the client asked for. No more, no less. No wasted bits over the wire.

@rj_dudley 3. APIs sitting behind GraphQL do not need to worry about serving every possible shape clients will want. Web wants more, mobile wants less? APIs don’t care. Clients ask for what they need. APIs return domain models. GraphQL transforms into ViewModels.

@rj_dudley 4. The GraphQL layer can then specifically optimize queries over the RESTful APIs, minimizing API calls necessary to resolve a query. Yes, it is work to implement each resolved, but the explicitness is so liberating.

@rj_dudley 5. And your clients have no idea what is happening behind the GraphQL façade. 1 call from the client could fan out to a dozen APIs (*in a good way). Orchestration stays out of the UI!

*This is good because it was still the server doing only what it was specifically built to do.

@rj_dudley 6. And we land in a mode where the UI code is dumb. So dumb. It is just using boring fetch calls and dealing with boring JSON responses that already match the desired shape so no boilerplate deserialization is necessary.

@rj_dudley 7. And then as the RESTful services change, get combined or divided, it is even more boring because the clients don’t even have to accommodate it. You only update the affected resolvers in GraphQL and the client is completely oblivious. Yawn.

@rj_dudley And here is another detail we have found important and highly successful:

Our GraphQL layer IS NOT implemented or operated by the teams building RESTful services. The UI teams build that layer and @howard_dierking’s team provides the platform and runs the service.

@rj_dudley @howard_dierking This lets the service teams concentrate on REST and the domain model. GraphQL is an implementation detail of the UI layer—a technology chosen by UI, not services.

@rj_dudley @howard_dierking This has avoided the whole REST vs. GraphQL debate with each of the dozens of service teams building APIs. They get to do their thing the way they want. For all they care, the UI consumes their services directly. We just happen to put a GraphQL server in between.

@rj_dudley @howard_dierking We can centralize the GraphQL implementation into a smaller community of developers where we can foster reuse and commonalities more easily.

@rj_dudley @howard_dierking Service teams are not burdened with *also* knowing and doing GraphQL. If they had to, they would inevitably look for ways to skip a layer, violating the separation of concerns.

@rj_dudley @howard_dierking I often refer to using GraphQL as a having a double-paned window. UI cannot reach APIs directly; GraphQL is in between as insulation, reducing concerns on both sides. GraphQL helps both the UI and API layers as a result.

@rj_dudley So what are the downsides of #GraphQL?

1. Having to justify it when first adopting it or before enough service teams realize it will only benefit them.

@rj_dudley 2. It is indeed yet another layer of ceremony where every single UI interaction needs to be thought through and implemented specifically (or covered by existing resolvers).

@rj_dudley 3. It takes notable calendar time to design the schema thoughtfully such that it will have backwards compatibility as it grows over time.

There is no versioning and the schema must be additive only (or with backwards compatible implementation detail changes).

@rj_dudley Note: Breaking changes are possible, but you must phase it: add new schema, rollout compensating changes to ALL clients, remove old schema.

@rj_dudley 4. It is yet another service to run and it is a single point of failure if not run well.

@rj_dudley 5. Features like paging and filtering and sorting are not built in and require that you invest in defining your patterns and reusable types.

@rj_dudley 6. For a big organization, you must intentionally create and foster a community of GraphQL contributors to ensure consistency and reuse.

@rj_dudley (Duplicating the same effort that should exist across API teams)

@rj_dudley 7. It works best when there is a single GraphQL server fulfilling the whole schema. That requires a single service that multiple teams can contribute resolvers to. That is where @howard_dierking’s team comes in for us—they build a platform we can publish resolver packages to.

@rj_dudley @howard_dierking But I consider most of these to be human problems, not technology problems, and I like that trade-off.