Service Clients

Why to define service contracts declaratively?

Typically in a distributed SOA environment, the service owners provide client libraries for their users which includes data models and methods to make RPC calls (Ex: JSON over HTTP). A few issues with this approach are

1. Client libraries come with transitive dependencies which could cause conflicts at aggregator service which talks to multiple other services.
2. Contract changes don't get published explicitly and don't follow semantic versioning.
3. Actual implementation of RPC method calls (say using apache's http connection pool) wrapped in hystrix/phantom could vary with services resulting in code duplication. Add to this other cross cutting concerns like metrics to get client side view of a service, authorization mechanisms like OAuth.

In Poseidon, we wanted to have an uniform way of accessing services (at least Http based services for now) and detach the finer design choices or implementation details from the actual service contracts, so that choosing a different encoding and RPC mechanism can be done at a central place.

We also wanted service owners to define their contracts explicitly in a centralised place so that it can be put under review by users and other SMEs as well as provide automatic semantic versioning (Ex: if we detect a backward incompatible change in contract including request, response objects, we can bump up major version).

Hence we decided to declare service client contracts (including request, response objects) in a language neutral way. Poseidon comes with code generator that reads these declarations and generates interfaces, implementations, request and response objects (in Java for now). The generated implementation is highly opinionated (in terms of using Phantom, JSON serialization over HTTP with connection pooling, request caching etc) and closed for modifications. Standard configurations like actual end points, concurrency, connection pool size etc can be specified at runtime.

How is service client defined?

A sample service client is defined here using a custom JSON Schema