GraphQL for service-to-service communication protocol

GraphQL Tokyo Meetup #9 at Repro Inc.

1. GraphQL for service-to-service communication protocol 2019-12-06 GraphQL Tokyo #9 @Repro Inc.
2. @qsona Web Engineer at Quipper Limited
3. Today's Topic: GraphQL is a suitable protocol not only for Frontend but also for service-to-service communication
4. Microservices • Number / Size of services,
 I don't care (just assume N>=2) • They cooperate with each other
 by communicating on some API protocol
5. Many people use REST / gRPC • For internal API protocol, GraphQL is currently not a popular choice • Of course, REST (JSON over HTTP) and gRPC are
 very good options
6. Why don't people use GraphQL? • "No need to use GraphQL internally because
 the network cost of internal communication is low" • • GraphQL has many other benefits!
7. 3 reasons why we should use GraphQL for service-to-service API protocol • 1. Easy to evolve our services • 2. Good API Interface and documentation system • 3. Easy to make GraphQL Aggregation Layer for Frontend
8. 3 reasons why we should use GraphQL for service-to-service API protocol • 1. Easy to evolve our services • 2. Good API Interface and documentation system • 3. Easy to make GraphQL Aggregation Layer for Frontend
9. Make our services easy to evolve • Services need to be evolved independently • This is one goal of microservices architecture • We often want to make changes for APIs • explicitly or implicitly • All the changes possibly break the consumers using that service
10. How to avoid breaking consumers? • Consumer won't be broken by irrelevant changes • Provider can be aware when a change will break some consumers
11. • Consumer won't be broken by irrelevant changes • Provider can be aware when a change will break some consumers
12. Consumer should be Tolerant • https://martinfowler.com/bliki/TolerantReader.html
13. A bad example (in Ruby) Response Body { "a": 1, "b": 2 } • An example of consumer code • Do you find why this code is bad?
14. Response Body { "a": 1, "b": 2, "c": 3 } A bad example (in Ruby) • It's not tolerant because
 it will be broken by just adding a new field to the API payload
15. Response Body { "a": 1, "b": 2, "c": 3 } How to fix it • We must explicitly pick the fields we use
16. Tolerant Reader in GraphQL • In GraphQL world, consumers are always Tolerant at a certain level • Consumers explicitly define
 what they need • If some unused fields are added / deleted, it should never be broken
17. • Consumer won't be broken by irrelevant changes • Provider can be aware when a change will break some consumers
18. How can providers be aware of the breaking changes itself? • Ask to other teams manually • It's necessary, but we want to reduce it as much as possible • Use Contracts between Consumer and Provider • (c.f. Consumer-driven Contract Testing) • Check Production API Logs
19. How providers can be aware of the breaking changes itself? • Use Contracts between Consumer and Provider • Check Production API Logs
20. Persisted Query • A technique that forces consumers to pre-register queries
 before they use them
 (e.g. build steps)
21. Persisted Query • A technique that forces consumers to pre-register queries
 before they use them (e.g. build steps) • Benefits: • Avoid executing unknown queries (which can be harmful)
 in provider service • Reduce the size of request payload • Enable to use HTTP GET Method, and cache on CDN
22. Persisted Query • Persisted Query can be regarded as Contract • Provider can check the persisted queries, and know what kind of fields are being used now • Provider can write tests to assure these queries can be used correctly,
 and run them in CI
 (≒ Consumer-driven Contract Testing)
23. How providers can be aware of the breaking changes itself? • Use Contracts between Consumer and Provider • Check Production API Logs
24. Field-level Logs • On GraphQL, we can check the logs in field-level • If a field doesn't show up in logs, that field is most likely deletable • On REST/gRPC, we can see only logs per endpoints
25. GraphQL helps us to evolve our services! • Consumer won't be broken by irrelevant changes • Provider can be aware when a change will break some consumers
26. 3 reasons why we should use GraphQL for service-to-service API protocol • 1. Easy to evolve our services • 2. Good API documentation/type system • 3. Easy to make GraphQL Aggregation Layer for Frontend
27. API documentation is important for microservices • API documentation makes our teams loose-coupling • It's also important that API documentation is always new and valid • It should be declarative and be used for request/response validation
28. GraphQL and API docs • GraphQL Type system and GraphiQL perfectly works • Compare to OpenAPI, GraphQL Type system is tightly coupled with the actual implementation • OpenAPI itself is just a declarative documentation • To validate request and response, we need some other tool
 (e.g. interagent/committee is an implementation for Ruby)
29. 3 reasons why we should use GraphQL for service-to-service API protocol • 1. Easy to evolve our services • 2. Good API documentation/type system • 3. Easy to make GraphQL Aggregation Layer for Frontend
30. GraphQL Aggregation Pattern • This pattern seems getting popular • It indicates that GraphQL API is very useful for Frontend Developers
31. GraphQL Aggregation Pattern • There is an Impedance Mismatch between REST/gRPC and GraphQL • Mapping REST/gRPC API to GraphQL Type is not just annoying, but also increasing points of failure • I feel it's usually a bit excessive architecture • (Sorry, I know google/rejoiner but didn't try by my hand)
32. If Backend APIs are also GraphQL • No impedance mismatch • It can reuse downstream schemas, so it can be thin layer • => Apollo Federation
33. Conclusion
34. Conclusion • GraphQL is also good for service-to-service communication protocol because • It makes easy to evolve our services without breaking consumers • It provides good API type and documentation system • It makes easy to make GraphQL Aggregation Layer for Frontend
 (which is already thought to be very useful)