I’m going to share the experience of creating a platform-level client library for communication between internal services. The talk partially covers topology and protocols related decisions we made. But the main focus is the Ruby library that defines the inter-service communication framework using business-related abstractions.

1. Pivorak meetup, Lviv, September 6
Business-friendly library for
inter-service communication
Anton Mishchuk

2. About me
- Lead software engineer
at Matic Insurance Services Inc
- We are hiring!
- Contact Iryna Sulatska
- linkedin.com/in/sulatskaya
- GitHub: antomi
- Medium: @anton.mishchuk

3. Goal
- Share our thoughts about the approaches to
inter-service communication
- Discuss in details the library we designed
for the communication

4. Agenda
- A little bit of history:
- How did we create a technical dept
- Approaches to inter-service communication:
- API-gateway vs Service Mesh
- REST vs Messaging
- Business-friendly library (BFL):
- One library for the whole platform

5. Evolution of the Matic platform
History

6. About Matic
- Matic is an insurance agency
- We integrated with ~20 insurance companies
- There are several inter-connected applications
(servicers) inside the Matic platform
- Almost all the services are written using Ruby

7. The beginning
S#1
Agents
Company #1
Company #2
Company #3Customer

8. Synchronous communication via HTTP REST (JSON)
Next steps
S#1
Agents
Company #1
Company #2
Company #3
S#3S#2

9. Sync and Async Communication via HTTP REST (JSON)
More and more services
S#1
S#3S#2
S#5S#4
S#6
API
Gateway

10. - Lots of services with heterogeneous API:
- No client libraries (plain JSONs)
- Naming collisions
- Data duplication between services
- It’s hard to make changes and introduce new services
Technical debt

11. Or a least to make a plan for payments
It’s time to pay the debt

12. Decisions we had to make
- 1. Topology
- Single communication hub (API Gateway)
- Service Mesh
- 2. Protocol:
- HTTP (sync)
- Messaging (async)
- 3. Client libraries:
- Do we really need them?

13. API Gateway
1. Topology
Service Mesh
S#1
S#4S#3
S#2
API
Gateway
S#1
S#4S#3
S#2

14. Pros:
- One place for the Platform level
API and
- “Facade” API - API built on top of
existing API
- Simple services discovery and
configuration
- One single point to integrate with
API Gateway
Cons:
- Single point of failure
- Hard to debug failures
- Part of business logic is here
- Who is responsible?

15. Pros:
- No single point of failure
- All the business logic is inside the
particular service
- Easy to debug
Service Mesh
Cons:
- Looks much more complex
- Services discovery and
configuration is in every project
- “Facade” API is not possible

16. Final decision
Service Mesh with API Gateway for external requests
S#1
S#4S#3
S#2
API
Gateway

17. - Services discovery and configuration
- “Facade” API
We decided to implement them on “library” level
What about API gateway features?

18. HTTP REST:
- Request/Response
- Synchronous
- One recipient
2. Protocol
Message Queues:
- Fire and forget
- Asynchronous
- Many recipients

19. Final decision - use both
HTTP REST:
- When you GET smth and expect immediate response
- When you DO smth and expect immediate result
Message Queue:
- When you INFORM about smth and
don’t need a feedback

20. 3. Client libraries
- General rule - you must have them!
- No error-prone plain JSON
- The same team develop endpoints and library
- Responsibility of request formation and validation goes
to the team that supports an endpoint
- Documented by code
- There are no drawbacks at all!

21. Client libraries
- If there are 10 services, there are 10 libraries
- It’s ok, in general
- But what if we put all of them into one single gem?

22. Single client library. Naive approach
- Just put all code into one gem
- Namespace functionality for each project
- And that’s it

23. Naive approach problem!
Existing abstractions in our APIs
don’t always correspond to business abstractions!

24. Single client library. Correct approach!
- Define platform-level models
- models that reflect domain and are common for every (most) service
in the platform: customer, property, lead, quote, policy.
- Define platform-level actions
- actions that reflect domain: “create customer”, “request quotes”
- operate with platform-level models

25. Business-friendly library
Palantir

26. Сhallenge #1: Proper naming
- Problem:
Some entities have the same name in projects but
actually maps to different domain models:
- Our examples: policy/prior_policy, etc
- Solution:
Think carefully about names for your entities!
Rename them properly.

27. Сhallenge #2: Data duplication
- Problem:
Some entities are stored in different projects:
- Our examples: customer, property, quotes, etc.
- Solution:
Find a proper place to store entities
Create a separate storage for entities that are used by
several services.

28. Сhallenge #3: API redesign
- Problem:
Redesign API endpoints for most of the projects
- After all changes mentioned above existing API becomes obsolete
- Solution:
- Just do it!

29. Models and actions
Palantir internals

30. Models
- Data structures with validation and serialization
- Defines attributes
- The way of validation (include ActiveModel::Validations)
- The way of serialization (include ActiveModel::Serializers::JSON)
- Can be reused in the projects
- Validation before actual request

31. Actions. Questions
- Wrap HTTP GET requests
- For fetching information from services
- Examples: GetProperty, ListPeople, etc.

32. Actions. Commands
- Wrap POST/PUT/DELETE requests
- For data creation and modification
- Examples: CreateProperty, RequestQuote, etc.

33. Actions. Statements (events)
- Wrap asynchronous communication
via Message queue
- Information messages that are broadcasted
on the platform level
- Consumed by any interested subscribers
- Example: PropertyChanged, QuoteFound

34. Actions interface
Remote Procedure Call (RPC)

35. Response
Call the action and get “response” object

36. Response statuses
- success
- Everything is fine. Results are available in response
- invalid
- Validation error on client side
- fail
- Smth went wrong on server side

37. Validation and defaults
- Validation before an actual request
- Simple validation
- More sophisticated one is on server side
- Set defaults for attributes

38. “Facade” API
- Complex actions/models build on top of
service-specific ones
- Example: SearchProperty

39. Service discovery
- Location
- Protocol
- Authentication

40. Profit for engineers and product managers
Conclusion

41. BFL for engineers
- Introduce Ruby object interface to the whole platform
- Defines “platform language”
- Documents all the APIs. In one place. By code

42. BFL for product managers
- Defines set of models (nouns) and actions (verbs)
available in the platform
- Business and engineers speak one “platform language”

43. Communication is important!

44. Questions?
Thank you!
Remember, we are hiring!