GraphQL for service-to-service communication protocol

GraphQL Tokyo Meetup #9 at Repro Inc.

Transcript

1. GraphQL for service-to-service
   communication protocol
   2019-12-06 GraphQL Tokyo #9 @Repro Inc.
   

   View Slide

2. @qsona
   Web Engineer at Quipper Limited
   

   View Slide

3. Today's Topic:
   GraphQL is a suitable protocol
   not only for Frontend
   but also for service-to-service communication
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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!
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
    

    View Slide

11. • Consumer won't be broken by irrelevant changes
    • Provider can be aware when a change will break some consumers
    

    View Slide

12. Consumer should be Tolerant
    • https://martinfowler.com/bliki/TolerantReader.html
    

    View Slide

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?
    

    View Slide

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
    

    View Slide

15. Response Body
    { "a": 1, "b": 2, "c": 3 }
    How to fix it
    • We must explicitly pick the fields we
    use
    

    View Slide

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
    

    View Slide

17. • Consumer won't be broken by irrelevant changes
    
    • Provider can be aware when a change will break some consumers
    

    View Slide

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
    

    View Slide

19. How providers can be aware of
    the breaking changes itself?
    • Use Contracts between Consumer and Provider
    • Check Production API Logs
    

    View Slide

20. Persisted Query
    • A technique that forces consumers
    to pre-register queries

    before they use them

    (e.g. build steps)
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

23. How providers can be aware of
    the breaking changes itself?
    • Use Contracts between Consumer and Provider
    
    • Check Production API Logs
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

30. GraphQL Aggregation Pattern
    • This pattern seems getting popular
    
    • It indicates that GraphQL API is very
    useful for Frontend Developers
    

    View Slide

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)
    

    View Slide

32. If Backend APIs are also GraphQL
    • No impedance mismatch
    
    • It can reuse downstream
    schemas, so it can be thin layer
    
    • => Apollo Federation
    

    View Slide

33. Conclusion
    

    View Slide

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)
    

    View Slide