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

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 (08/2022): The patterns featured in this catalog form the core of a new book in Vaughn Vernon’s Signature Series at Pearson, scheduled for publication in December 2022. Read more about these exciting news on the API design patterns website.

Published Refactorings

An overview of the refactorings, set in italics, is (links available on the Refactorings by Target page):

You may want to start browsing via the Refactorings by Stakeholder Concerns or Refactorings by Smells / Drivers 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. The Backlog provides a preview of other potential refactorings.1

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.

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.

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 modelled explicitly)? Which design problems pertain to this refactoring, and which design options are currently chosen to resolve them?
  • Smells / Drivers. 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 backwards 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.

For refactorings at the code level and their corresponding smells, we recommend visiting Refactoring.Guru.

The broader context is explained on the website “Architectural Refactoring for the Cloud (ARC)”.


We 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.


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 (Chapter 3 in “Aligning Agile Processes and Software Architectures”). Morgan Kaufmann.

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.

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.

Zimmermann, Olaf. 2015. “Architectural Refactoring: A Task-Centric View on Software Evolution.” IEEE Software 32 (2): 26–29.

  1. Does a discipline/practice of “meta refactoring” exist? 

  2. 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.