Slide 1
Slide 1 text
GraphQL for service-to-service
communication protocol
2019-12-06 GraphQL Tokyo #9 @Repro Inc.
Slide 2
Slide 2 text
@qsona
Web Engineer at Quipper Limited
Slide 3
Slide 3 text
Today's Topic:
GraphQL is a suitable protocol
not only for Frontend
but also for service-to-service communication
Slide 4
Slide 4 text
Microservices
• Number / Size of services,
I don't care (just assume N>=2)
• They cooperate with each other
by communicating on some API protocol
Slide 5
Slide 5 text
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
Slide 6
Slide 6 text
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!
Slide 7
Slide 7 text
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
Slide 8
Slide 8 text
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
Slide 9
Slide 9 text
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
Slide 10
Slide 10 text
How to avoid breaking consumers?
• Consumer won't be broken by irrelevant changes
• Provider can be aware when a change will break some consumers
Slide 11
Slide 11 text
• Consumer won't be broken by irrelevant changes
• Provider can be aware when a change will break some consumers
Slide 12
Slide 12 text
Consumer should be Tolerant
• https://martinfowler.com/bliki/TolerantReader.html
Slide 13
Slide 13 text
A bad example (in Ruby)
Response Body
{ "a": 1, "b": 2 }
• An example of consumer code
• Do you find why this code is bad?
Slide 14
Slide 14 text
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
Slide 15
Slide 15 text
Response Body
{ "a": 1, "b": 2, "c": 3 }
How to fix it
• We must explicitly pick the fields we
use
Slide 16
Slide 16 text
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
Slide 17
Slide 17 text
• Consumer won't be broken by irrelevant changes
• Provider can be aware when a change will break some consumers
Slide 18
Slide 18 text
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
Slide 19
Slide 19 text
How providers can be aware of
the breaking changes itself?
• Use Contracts between Consumer and Provider
• Check Production API Logs
Slide 20
Slide 20 text
Persisted Query
• A technique that forces consumers
to pre-register queries
before they use them
(e.g. build steps)
Slide 21
Slide 21 text
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
Slide 22
Slide 22 text
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)
Slide 23
Slide 23 text
How providers can be aware of
the breaking changes itself?
• Use Contracts between Consumer and Provider
• Check Production API Logs
Slide 24
Slide 24 text
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
Slide 25
Slide 25 text
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
Slide 26
Slide 26 text
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
Slide 27
Slide 27 text
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
Slide 28
Slide 28 text
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)
Slide 29
Slide 29 text
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
Slide 30
Slide 30 text
GraphQL Aggregation Pattern
• This pattern seems getting popular
• It indicates that GraphQL API is very
useful for Frontend Developers
Slide 31
Slide 31 text
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)
Slide 32
Slide 32 text
If Backend APIs are also GraphQL
• No impedance mismatch
• It can reuse downstream
schemas, so it can be thin layer
• => Apollo Federation
Slide 33
Slide 33 text
Conclusion
Slide 34
Slide 34 text
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)