Note: This is a preview release and subject to change. Feedback welcome! Contact Information and Background (PDF)

For Any Refactoring: Test, Explain, Let Know and Learn (TELL)

Having applied a refactoring, always apply the TELL steps (Test, Explain, Let Know and Learn):

  • Test the updates (locally and end-to-end),
  • Explain the new design in the API description (including version number),
  • Let API clients and other stakeholders know about the change (is it compatible?), and
  • Learn about the effectiveness of the refactoring (as well as negative side effects) with logging and other observation instruments.

Other General Hints and Pitfalls to Avoid

Each refactoring has a section called “Hints and Pitfalls to Avoid”. Here are a few tips that apply to most if not all refactorings:

  • Establish measurable quality goals to be able to decide that it makes sense to refactor and to evaluate whether you succeeded. Alternatively, include API design quality issues in your technical risk management. The Design Practice Repository provides further guidance.
  • Execute the steps under “Instructions” in an all-or-nothing manner. If it turns out that you cannot complete a refactoring successfully, undo all steps already performed to roll back to the initial state.
  • Make sure that your conceptual, platform-independent design, its technology- and platform-specific refinement, the implementation, the tests and the documentation of all of these artifacts stay current and consistent. Test under normal conditions, but also edge cases and error scenarios.
  • Try to decouple the API from its implementation to be able to evolve and refactor independently.
  • Evaluate whether the smells are removed (or that at least some desired qualities have improved somewhat); record any remaining or new technical debt and identify additional follow-on refactorings.
  • Check whether the same refactoring makes sense in other places a) to remove other smell instances or b) to preserve conceptual integrity (a term from Fred Brooks).

Sample Application: Lakeside Mutual

The Lakeside Mutual application is a sample microservice architecture we built to demonstrate API design and patterns. It comprises several Spring Boot microservices offering APIs that are used by clients written in React, Vue.js, and Node.js:

The code is available at GitHub and licensed under the Eclipse Public License.