Use Case 1 - Namphibian/YACM GitHub Wiki

Introduction:

A consumer using the API periodically to maintain a copy of the providers customers.

Discussion:

A common mistake which is common in REST API design is too low level API's. The amount of "REST" api's which are essentially fine grained persistent storage HTTP exposures in reality is shocking. Having a fine grained CRUD like API poses some problems which makes the API harder to use, harder to maintain and harder to expand:

  • Exposure of database/persistent storage resources to consumers. This is tight coupling.
  • Moving business logic into the consumer. This breaks abstraction.
  • Loss of business domain events. Since operation are technical and not business oriented we have a disconnect. For example creating a client might require creation of a customer and then address information. However business refers to this as customer enrollment. It is a single action according to business. In a fine grained CRUD interface there is no enrollment event. Thus it is virtually impossible to track how many new clients really enrolled as a customer creation event is not equal to a client enrollment event.

A more detailed discussion around this can be found at this must read blog

Thus in the design I am proposing we do not expose CRUD type interfaces but a more coarse grained interface. This allows me to record business events. These events will provide a client with enough information to remain in a synchronized state.

The following events are exposed:

  1. Customer Enrollment: A new customer is created, this allows you to keep track and query the history of new customer i.e. creation.
  2. Customer Exit: A customer exits the business and has been removed from the system. This will allow you to keep track and query delete events
  3. Customer Address Change: A customer updated their address information. This allows updates to be tracked and queried.
  4. Customer Details Change: A customer updated their personal details.This allows updates to be tracked and queried.

Conclusion:

By using a coarser grain API we were able to expose finer grained event to use in tracking changes to the resources in the API. A consumer can choose what to track and can query different synchronization paths in parallel e.g. they can run person and address updates in parallel. This allows higher throughput.

Proposed enhancements:

We need to be able to throttle client. As these synchronizations can be big we need to be able to send a HTTP response code back to clients saying you are being throttled back of. A request to implement this has been raised.