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

Interface Refactoring Catalog

Welcome to the Interface Refactoring Catalog, a collection of API refactorings and related architectural refactorings.

Published Refactorings

Overview:

IRC Overview: 9 Refactorings Currently Available

Links to the refactorings:

Scope Refactoring Alternative or Reverse Refactoring  
Request Message Introduce Pagination Bundle Requests  
Any Message Extract Information Holder Inline Information Holder  
  Introduce Data Transfer Object    
Operation Move Operation Rename Operation  
Endpoint Extract Endpoint Merge Endpoints  

See our Backlog for a preview of other refactorings we are currently working on.

Why Refactoring

Refactoring refers to the practice of improving a software system without changing its external/observable behavior. Think of cleaning-up a piece of code or putting finishing touches on a design, like making sure all names are well-chosen or breaking up a long piece of code into several parts. The purpose of a refactoring can also be the alignment of the software with a design pattern (Kerievsky 2004). Once you start to add new features or fix bugs, you are not refactoring anymore.

A refactoring is performed as a series of small steps that always keeps the software in a functioning state, and should be accompanied by a comprehensive suite of tests. For example, when moving a method between classes, a forwarding method that delegates calls from the original to the new class allows callers of the method to be migrated individually.

Introduction to Interface Refactoring

You are probably wondering what exactly we mean with “interface”, a term that has several meanings, from the Java keyword to describe a programming language concept to the “I” in API – Application Programming Interfaces. Zooming out from a single program and putting on our systems architecture hat, other types of interfaces1 start to appear.

Much has been written about refactoring in programming languages — the term originates there. Bill Opdyke wrote a PhD thesis on the subject (Opdyke 1992), and the term has been popularized by Martin Fowler (Fowler 2018) — but the concept and the activity have broader appeal. Architectural refactoring (Stal 2013) aims at improving the future evolvability of the software on the architecture level. This is also the level where this catalog is aimed at. Michael Stal gives one reason for refactoring, improving the future evolvability, but refactoring can target other non-functional requirements as well: “Improve at least one quality attribute without changing the scope and functionality of the system.”

Update (September 27, 2021): Our first research paper is available now (Stocker and Zimmermann 2021). It reports the results of a practitioner survey, defines the term “API refactoring”, and gives an outlook to the refactoring catalog presented on this website. The proposed definition is:

An API refactoring evolves the remote interface of a system without changing its feature set and semantics to improve at least one quality attribute.

The paper is available for download here.

Catalog Content Overview

Refactoring Template (Anatomy)

Each refactoring is documented in the same form:

  • Context and Motivation
  • Stakeholder Concerns (including Quality Attributes and Design Forces)
  • Initial Position Sketch (including Target(s))
  • Smells / Drivers
  • Instructions (Steps)
  • Target Solution Sketch (Evolution Outline)
  • Example(s)
  • Hints and Pitfalls to Avoid
  • Related Content

More Information

Also see the (older) OST IFS website “Architectural Refactoring for the Cloud (ARC)”.

References

Fowler, Martin. 2018. Refactoring: Improving the Design of Existing Code. 2nd ed. Addison-Wesley Signature Series (Fowler). Boston, MA: Addison-Wesley.

Kerievsky, Joshua. 2004. Refactoring to Patterns. Pearson Higher Education.

Opdyke, William F. 1992. Refactoring Object-Oriented Frameworks. USA: University of Illinois at Urbana-Champaign.

Stal, Michael. 2013. Agile Software Architecture. Morgan Kaufmann. https://doi.org/10.1016/B978-0-12-407772-0.00003-4.

Stocker, Mirko, and Olaf Zimmermann. 2021. “From Code Refactoring to API Refactoring: Agile Service Design and Evolution.” In Service-Oriented Computing, edited by Johanna Barzen, 174–93. Cham: Springer International Publishing.

  1. Merriam-Webster: “The place at which independent and often unrelated systems meet and act on or communicate with each other”. Note the German translation of interface “Schnittstelle” means the position where something is cut apart.