Interface Refactoring Catalog
Welcome to the Interface Refactoring Catalog, a collection of API refactorings and related architectural refactorings.
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.
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
- See here.
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)
- Hints and Pitfalls to Avoid
- Related Content
Also see the (older) OST IFS website “Architectural Refactoring for the Cloud (ARC)”.
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.
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. ↩