Interface Refactoring Catalog
Welcome to the Interface Refactoring Catalog, a collection of API refactorings and related architectural refactorings. The refactoring activities are described in a technology-neutral way for the most part, but their examples and implementation hints stem from HTTP resource API design and evolution.
News (10/2024): Our contribution to the EuroPLoP 2024 proceedings, “Pattern-oriented API Refactoring: Addressing Design Smells and Stakeholder Concerns”, is on its way. You can find the CC-BY-ND version of the paper here. All publications about IRC are available from the Articles and Books page.
News (07/2024): We present(ed) the next seven refactorings in Workshop B of EuroPLoP 2024. Stay tuned!
News (12/2023): Eight refactorings were workshopped at the 29th European Conference on Pattern Languages of Programs (EuroPLoP). The open-access paper, published by ACM, is available for download here.
News (12/2022): The patterns featured in this catalog form the core of a new book in Vaughn Vernon’s Signature Series at Pearson, published in December 2022. Read more about this exciting news on the API design patterns website.
The news posts of this site keep you updated.
Refactorings Catalog Overview
The following UML class diagram shows which refactorings we have collected (links to them are available on the Refactorings by Target page):
Figure 1: Refactorings by targeted API element; refactoring names in italics have been workshopped at EuroPLoP.
You may want to start browsing via the Refactorings by Stakeholder Concerns or Refactorings by Smells views. We advise to Test, Explain, Let Know and Learn when applying the refactorings.
Note: This is Version 1.0 of our catalog. We might extend it in the future — or refactor it.1 The Backlog provides a preview of other potential refactorings.
The latest MDSL Tools implement most of the refactorings. See the documentation on Transformations Related to Patterns and Refactorings and this blog post for details.
Why Refactoring
Refactorings remove “Software Design Smells” [Suryanarayana, Samarthyam, and Sharma 2014].
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 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 with 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 interfaces2 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. Olaf Zimmermann [Zimmermann 2015] defines an Architectural Refactoring as
[…] a coordinated set of deliberate architectural activities that removes a particular architectural smell and improves at least one quality attribute without changing the scope and functionality of the system.
Our research paper [Stocker and Zimmermann 2021] (available for download here) 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.
Many of the patterns that are the target to which we refactor are described in our pattern language for microservice and remote API design, first published in the EuroPLoP proceedings 2017 to 2020 and finalized in Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges [Zimmermann et al. 2022].
Target Audience
With this catalog, we target software developers and architects that develop, design, and maintain software systems. The majority of refactorings focus on the remote interface of these systems, their operations, endpoints, and messages. We do not target any specific domain or technology; every system exposing an API is a potential candidate. However, most of our experience comes from architecting and modernizing multi-channel enterprise applications as well as developing cloud-native applications that serve Web and mobile front-ends and interact with other Web services through HTTP APIs. We are more than happy to integrate contributions that apply our refactorings to other technologies that require different instruction steps or come with further hints and pitfalls to avoid – contact us!
Refactoring Template
Each refactoring is documented in the same form:
- Context and Motivation. Where (and under which circumstances) is this refactoring eligible? And why?
- Stakeholder Concerns (including Quality Attributes and Design Forces). Which non-functional requirements and constraints are impacted by this refactoring?
- Initial Position Sketch (including Target Element(s)). Which design model elements have to be changed, e.g., components and connectors (if modeled explicitly)? Which design problems pertain to this refactoring, and which design options are currently chosen to resolve them?
- Smells. Identify the smells that indicate a problem of the architecture or API: When and why should this AR be considered?
- Instructions (Steps). How can the AR be applied and validated? What is the right series of steps to follow?
- Target Solution Sketch (Evolution Outline). Which design options should be chosen now? How does the target solution look like? In particular, impact on API clients, what can be done to mitigate? Is there a variant of the refactoring, e.g., for backward compatibility?
- Example(s).
- Hints and Pitfalls to Avoid.
- Related Content.
Some suggested/featured content is Introduce Pagination, Segregate Commands from Queries and Introduce Data Transfer Object
More Information
A Glossary introduces terms and defines the vocabulary for the refactoring texts. The Open Group has published a chapter on Continuous Architectural Refactoring [Open Group 2020]. Refactoring can also be applied to databases, as Ambler and Sadalage [2006] show in “Refactoring Databases: Evolutionary Database Design.” Yoder and Merson [2022] present “Strangler Patterns” that can be used to evolve a monolith into microservices.
For refactorings at the code level and their corresponding smells, we recommend visiting Refactoring.Guru. The Cloud Adoption Patterns Website has a section on Cloud Refactoring. Refactoring serverless applications is covered in Refactoring to Serverless. A catalog of Domain-Driven Refactorings is also in the making.
The broader context is explained on the website “Architectural Refactoring for the Cloud (ARC)”.
Acknowledgements
We want to thank the participants of the Euro-PLoP 2023 Writers’ Workshop for their valuable feedback. We also thank Andrei Furda for his reviews of intermediate versions of the refactorings. Daniel Lübke reviewed the refactorings related to versioning and life cycle guarantees. The MAP team wrote up many of the the patterns that are featured as refactoring targets.
References
Ambler, Scott W., and Pramodkumar J. Sadalage. 2006. Refactoring Databases: Evolutionary Database Design. Addison-Wesley.
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.
Open Group. 2020. Open Agile Architecture™: A Standard of the Open Group. The Open Group Series. Van Haren.
Stal, Michael. 2013. Agile Software Architecture (Chapter 3 in “Aligning Agile Processes and Software Architectures”). 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. https://doi.org/10.1007/978-3-030-87568-8_11.
Suryanarayana, Girish, Ganesh Samarthyam, and Tushar Sharma. 2014. Refactoring for Software Design Smells: Managing Technical Debt. 1st ed. San Francisco, CA, USA: Morgan Kaufmann Publishers Inc.
Yoder, Joseph W., and Paulo Merson. 2022. “Strangler Patterns.” In Proceedings of the 27th Conference on Pattern Languages of Programs. PLoP ’20. USA: The Hillside Group.
Zimmermann, Olaf. 2015. “Architectural Refactoring: A Task-Centric View on Software Evolution.” IEEE Software 32 (2): 26–29. https://doi.org/10.1109/MS.2015.37.
Zimmermann, Olaf, Mirko Stocker, Daniel Lübke, Uwe Zdun, and Cesare Pautasso. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley Signature Series (Vernon). Addison-Wesley Professional.