Wide adoption of Microservice Architecture presents a whole new set of challenges for us as developers. Some of them are well-known and understood. About others we do not think until they strike us out of the blue and we spend a lot of sleepless nights trying to figure them out. And communication between services in distributed system is one of the latter. During this Microservice Architecture Odesa #TechTalk we will talk about how to prevent your microservices from becoming a modern-world Tower of Babel. We will discuss how to select appropriate communication mechanisms for most common cases in a distributed system, how should we define API contracts for each of them and what tools are available for us to keep them consistent and evolve them over time. We will touch following topics:  REST vs RPC vs Messaging and how not to get lost with your options.  Contract First development and how it can save time in multi-team environment.  SwaggerHub as a single Point of truth for REST API  Best practices for gRPC contracts and how to deal with changes in them. About speaker: Andrii Barsukov is Senior .NET developer at Lohika, with 5+ years of commercial experience in development of microservice applications. Currently participating in development of microservice-based financial system, which includes 20+ microservices developed by 10 separate development teams. And some of the challenges that we faced during its development I'd like to share.

1. Keep Your Contracts in Check:
Design and Evolution of APIs in
Microservice Architecture

2. About Me
• .NET Developer at Lohika
• 5+ years of commercial
experience
• 3+ years at Lohika
• Participated in development of 4
microservice-based systems,
from 3 to 20+ services each.

3. • Ways of interservice communication and how not to get lost with
your options.
• API First development and how it can save time in multi-team
environment.
• SwaggerHub as a single Point of truth for REST API
• Best practices for gRPC contracts and how to deal with changes in
them.
• Kafka Schema Registry - contract coordinator for different
messaging scenarios
Agenda

4. Tourist Agency Application
Happy Monolith Past
SQL
TripPlanningService
CustomerService HotelBookingService
CarRentalService

5. Bright Microservice Future
SQL
TripPlanningService
CustomerService HotelBookingService
CarRentalService
SQL
Mongo
DB
????

6. Synchronicity
• Synchronous protocol
• Asynchronous protocol
Number of
receivers
• Single receiver
• Multiple receivers
Communication types

7. Synchronous protocol ≠ Synchronous Communication
Client
Trip Planning
Service
Car Booking
Service
Customer
Service
HTTP Sync
Request
HTTP Sync
Response
HTTP Sync
Request
HTTP Sync
Response
HTTP Sync
Request
HTTP Sync
Response
Client
Trip Planning
Service
Car Booking
Service
Customer
Service
HTTP Sync
Request
HTTP
Polling
HTTP
Polling
HTTP Sync
Response
HTTP
Polling
HTTP Sync
Request
HTTP Sync
Response

8. Number of Receivers
Single Receiver - Command
• At Least Once delivery
• Exactly Once processing
• Order of execution is important
• Producer expects to receive
response
Multiple Receivers - Event
• Fire and Forget
• Louse Coupling between
producers and consumers
Trip Planning
Service
Car Booking
Service
Book a car for
specific dates
Customer
Service
Car Booking
Service
Trip Planning
Service
Hotel Booking
Service
Customer Info
Changed

9. Who Owns the Contract?
Single Receiver - Command
• The inbound queue identifier
• The format of the processed
command types
Multiple Receivers - Event
• The topic identifier
• The format of all emitted
events

10. Command Model
Consumer Producer
Business Logic Implements business Logic Triggers business logic
Quantity Always one Often many
Autonomy Can run on its own Fails if no consumer
Consumer owns the contract

11. Event Model
Consumer Producer
Business Logic Implements business Logic Reports an event
Quantity Usually many Only one
Autonomy Subordinate to producer Can run on its own
Producer owns the contract

12. Development Approaches
Code First
Contract First

13. Code First
Team Gonzo - Customer Service
Team Kermit – Car Rental Service
Investigate Implement Test
Investigate Implement Test

14. Contract First
Team Gonzo - Customer Service
Team Kermit – Car Rental Service
Define API
Contract
Investigate Implement
Investigate Implement Test
Test
Agree on API
Contract

15. • Development teams does not block each other
• Good and consistent communication between teams
• Consistent API models
• Separation of concerns
• Reusability
• Easy documentation
Contract First

16. REST Contracts - OpenAPI
API description format for REST APIs. An OpenAPI file allows you to
describe your entire API, including:
• Available endpoints (/users) and operations on each endpoint (GET
/users, POST /users)
• Operation parameters Input and output for each operation
• Authentication methods
• Contact information, license, terms of use and other information.

17. Demo Time

18. gRPC Contracts – Protocol Buffers
ProtoBuf
Definitions
protoc
Compiler
.NET
Go
Kotlin
gRPC Server
gRPC Client
2. Compile
1. Define 3. Implement

19. Keeping ProtoBuf in Line
Pick Style Guide
• Google’s Style Guide
• Uber’s Style Guide (V1/V2)
Lint your ProtoBuf files & Check for Breaking Changes
• Prototool
• Buf
Setup Mock Servers
• GripMock

20. Messaging Contracts – Kafka Schema Registry

21. Compatibility Types
Compatibility Type Changes Allowed Upgrade First
BACKWARD - Delete Fields
- Add optional fields
Consumers
FORWARD - Add fields
- Delete optional fields
Producers
FULL - Add optional fields
- Delete optional fields
Any order
NONE - Any changes Usually - custom migration logic

22. Useful Tools
• Stoplight Studio - https://stoplight.io/studio/
• Spectral - https://stoplight.io/open-source/spectral/
• OpenAPI-diff -https://github.com/OpenAPITools/openapi-diff
OpenAPI Tooling
• SwaggerHub - https://swagger.io/tools/swaggerhub/
• SwaggerHub CLI - https://github.com/SmartBear/swaggerhub-cli
SwaggerHub
• Prototool - https://github.com/uber/prototool
• GripMock - https://github.com/tokopedia/gripmock
gRPC Tooling

23. Thank You!