The document discusses best practices for managing APIs in a microservice architecture, emphasizing the importance of keeping contracts updated and utilizing tools like Swaggerhub and Kafka Schema Registry. It outlines different approaches to interservice communication, including synchronous and asynchronous protocols, and details the benefits of API-first development in multi-team environments. Additionally, it addresses contract ownership, development strategies, and provides a list of useful tools for REST and gRPC API management.

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!