How to Improve API Quality? A Catalog of Remote Interface Refactorings

An Interface Refactoring Catalog (IRC) complementing “Patterns for API Design” is available online. This post takes you through the IRC website and features selected catalog entries.

Interface Refactoring Catalog (IRC) Overview

Why IRC? It provides “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” (source: https://interface-refactoring.github.io/).

Scope and Background

IRC focusses on RESTful Web APIs and other remote APIs (gRPC, GraphQL etc.); messaging channels and endpoints also are in scope. Local APIs inside programs are out of scope, as a rather rich set of resources already exists.

The IRC homepage provides an alphabetical index and explains what the term “refactoring” means in this context:

There are 25 API refactorings in total. 17 out of 25 catalog entries have design patterns as their target solutions:

• 11 of these patterns come from the “Patterns for API Design” book and website. An example is Introduce Pagination.
• 3 entries target “Distribution Patterns” (aka Client-Server Cuts), appearing in a paper from the late 1990s that stayed relevant. Example: Split Application Backend Logic.
• 3 entries refer to other patterns: Command Query Responsibility Segregation, Data Transfer Object, and Version Mediator.

The remaining eight IRC entries do not target patterns but have a structural nature. An example is Split Operation.

The IRC Template

The presentation of each IRC refactoring starts with a context and motivation, followed by stakeholder concerns including quality attributes and design forces. An initial position sketch shows which API parts or architectural elements are targeted. Each refactoring then lists smells that indicate problems with the initial solution.

A set of instructions explains how to transform the initial position sketch into a target solution sketch. Each refactoring presents a concrete example showing the refactoring in action, followed by a discussion of hints and pitfalls to avoid. Finally, related content is referenced.

Two of these sections go significantly deeper than the scope of “Patterns for API Design” allowed: instructions (step-by-step instructions) and hints and pitfalls to avoid (lessons learned, gotchas).

Sample Catalog Entries

Let’s pick one entry per entry type: refactoring to patterns, architectural refactorings and structural refactorings.

Add Wish List

Add Wish List refactors to an API design pattern, Wish List. Its motivating user story is:

As an API client, I want exact control over response message content so that I receive just the data I require to realize an application feature.

The target solution sketch includes the following figure:

Note the links to many other patterns and the presence of the List Evaluator component, from the solution sketch of the featured pattern.

Check out the “Instructions” section!

Separate Commands from Queries

Separate Commands from Queries is an architectural refactoring, targeting CQRS, a pattern from Event-Driven Architecture (EDA). It addresses the following concerns:

Clicking on a concern name takes you to an overview of all concerns, with links to IRC entries addressing them. Try flexibility or scalability!

The “Related Content” section in the catalog entry has many pointers to CQRS and EDA.

Rename Operation

Rename Operation is one of the structural refactorings. Its attacked smells are:

Clicking on the smell name takes you to the smell browser, which lists other IRC entries aiming at resolving it. Try Cryptic, misleading or unethical name.

You might want to take a look at the “Hints and Pitfalls to Avoid” in this IRC entry, as well as its three footnotes at the bottom of the page. 😉

A Brief Retrospective

Here are some of our take-aways. You can find more impressions in the news posts on the catalog website.

The writer’s workshop participants at EuroPLoP appreciated the IRC content; their feedback and suggestions helped on the way to papers and the website desribed in this post. Scope, depth in particular, was discusses intensively. The IRC entries primarily focus on describing the target solution and the way to get there rather than removing any mess in the initial position. Hence, our website provides a concerns browser and a smell browser to get started.

The monolith vs. … (fill in the decomposition approach that currently prevails here; 2014 to present: microservices) discussion and decision continues to be relevant. In this context, the terminology around layers and tiers is not consistent in the literature. To clarify, we picked up five distribution patterns, aka Client-Server Cuts (CSCs), first published in 1997 (!). These CSCs and our corresponding IRC entries agree that logical decomposition and physical distribution are two related but different architectural decisions (with deployment units as glue).

We noticed certain recurring text patterns when writing the “How to” and “Hints” sections of the catalog entries, which lead to the Test, Explain, Let Know and Learn (TELL) metaphor. TELL helped us express recurring hints in a more general way (we refactored the catalog entries in an “Extract Advice” move!).

We hope you will find IRC useful! Try the pointers to the website in this post, or find your way yourself. If you prefer an article format, the papers from EuroPLoP 2023 to 2025 (four content slices) are available for download here (PDFs, free authors copies or open access).

– Olaf (with Mirko Stocker, who reviewed this post)

PS: Fresh related content just became available: “A Pattern a Day”, light and free email-based learning, courtesy of our patterns co-author Daniel Lübke.