API design for data model with frequent field name updates

Question

I have an external data model framework with frequent updates to the names of fields. Say for an iteration I implement on

- EnterpriseModelObject
-- EnterpriseDomainContentList
--- EnterpriseDomainContent
-- ContentDeliveryResult
--- ErrorList
---- Error
--- WarningList
---- Warning

Another iteration this will become

- EnterpriseModelObject
-- EnterpriseContentList
--- EnterpriseContent
-- DeliveryResult
--- EnterpriseErrorList
---- EnterpriseError
--- EnterpriseWarningList
---- EnterpriseWarning

I have a number of microservices that require converting a variety of bean types to this model and back. For this I have a library that does the common work but I am still struggling with updates when my bean model changes.

The microservices are implemented to directly use the object names in the model and the library simply provides common conversion methods. So when I start updating the conversion library this breaks the unit tests in the service APIs. Ideally I want to be able to localize all object name changes to my library and the services will return the correct fields without requiring micromanagement.

What kind of approach should I take with the services so that they automatically use the updates without compilation or unit test issues?

Answer 1

You definitely have your work cut out for you. Due to the rate of change, and the requirements you have to constantly move to the new API versions, you have a limited set of options.

Option 1

Create a microservice that wraps this troublesome API. It's sole purpose is to provide your application a consistent interface. Your microservice would be deployed mapping to one version of the external API, and as new versions come out, you adapt it and redeploy it.

Even if you aren't currently using a microservices architecture, you have a means of staying current and making it useful with your deployed application. The benefits include:

• Microservice deployment schedule not tied to application deployment
• Consistent API smooths the churn and allows you to work with a known data model

Of course this is only easy if the API you are wrapping is web based. The caveats include:

• Increased latency as the API call is re-written and forwarded
• Limited to a subset of problems

Option 2

Create a component in your application that does the same thing as the microservice solution, but it is part of your code. You can deploy new versions of the service when it is ready, and perhaps select the correct implementation of the service depending on the version you are calling.

Benefits:

• No additional latency because the component is embedded in your code
• Not restricted to the types of APIs you call
• Consistent interface smooths the use of the troublesome API

Caveats:

• Deployment of new wrappers tied to deploying your application

The remainder of your options are just different flavors of the above options

Whether you abstract the object mapping code, or the whole API, the bottom line is that your solution needs to ensure the following:

• Code to fix broken adaptations is centrally located
• The external API object changes don't have a ripple effect throughout your code
• If at all possible, you have a means of adapting the changes to a set of known classes that have a more stable lifespan

I wish you luck. It is an ugly problem, and there are no pretty solutions. The general idea is to create an adapter at the right level of abstraction.

If staying on the bleeding edge is important, you need a way to deploy parts of your application at different rates. That's primarily why I included the microservice solution as option one.