Download Full Version ebook - Visit ebooknice.

com

(Ebook) Patterns for API Design: Simplifying

Integration with Loosely Coupled Message Exchanges
by Olaf Zimmermann, Mirko Stocker, Daniel Lubke,
Uwe Zdun, Cesare Pautasso ISBN 9780137670109,
0137670109
https://ebooknice.com/product/patterns-for-api-design-
simplifying-integration-with-loosely-coupled-message-
exchanges-55560336

Click the button below to download

DOWLOAD EBOOK

Discover More Ebook - Explore Now at ebooknice.com

 Instant digital products (PDF, ePub, MOBI) ready for you
Download now and discover formats that fit your needs...

Start reading on any device today!

(Ebook) Biota Grow 2C gather 2C cook by Loucas, Jason;

Viles, James ISBN 9781459699816, 9781743365571,
9781925268492, 1459699815, 1743365578, 1925268497
https://ebooknice.com/product/biota-grow-2c-gather-2c-cook-6661374

ebooknice.com

(Ebook) Matematik 5000+ Kurs 2c Lärobok by Lena

Alfredsson, Hans Heikne, Sanna Bodemyr ISBN 9789127456600,
9127456609
https://ebooknice.com/product/matematik-5000-kurs-2c-larobok-23848312

ebooknice.com

(Ebook) SAT II Success MATH 1C and 2C 2002 (Peterson's SAT

II Success) by Peterson's ISBN 9780768906677, 0768906679

https://ebooknice.com/product/sat-ii-success-
math-1c-and-2c-2002-peterson-s-sat-ii-success-1722018

ebooknice.com

(Ebook) Master SAT II Math 1c and 2c 4th ed (Arco Master

the SAT Subject Test: Math Levels 1 & 2) by Arco ISBN
9780768923049, 0768923042
https://ebooknice.com/product/master-sat-ii-math-1c-and-2c-4th-ed-
arco-master-the-sat-subject-test-math-levels-1-2-2326094

ebooknice.com
(Ebook) Cambridge IGCSE and O Level History Workbook 2C -
Depth Study: the United States, 1919-41 2nd Edition by
Benjamin Harrison ISBN 9781398375147, 9781398375048,
1398375144, 1398375047
https://ebooknice.com/product/cambridge-igcse-and-o-level-history-
workbook-2c-depth-study-the-united-states-1919-41-2nd-edition-53538044

ebooknice.com

(Ebook) Process-Driven SOA: Patterns for Aligning Business

and IT by Carsten Hentrich, Uwe Zdun ISBN 9781439889299,
1439889295
https://ebooknice.com/product/process-driven-soa-patterns-for-
aligning-business-and-it-4398102

ebooknice.com

(Ebook) Design Patterns with Java by Olaf Musch ISBN

9783658398286, 9783658398293, 3658398280, 3658398299

https://ebooknice.com/product/design-patterns-with-java-49132912

ebooknice.com

(Ebook) Antenna Theory & Design by Markus Voelter,

Michael Kircher, Uwe Zdun ISBN 9780470856628, 0470856629

https://ebooknice.com/product/antenna-theory-design-1273420

ebooknice.com

(Ebook) Empirical Studies on the Development of Executable

Business Processes by Daniel Lübke, Cesare Pautasso ISBN
9783030176655, 9783030176662, 3030176657, 3030176665
https://ebooknice.com/product/empirical-studies-on-the-development-of-
executable-business-processes-10796760

ebooknice.com
“APIs are eating the world. Organizations and collaborations are depending more and
more on APIs. For all these APIs to be designed, using patterns is a well-established way
of tackling design challenges. Patterns for API Design helps practitioners to design
their APIs more effectively: They can focus on designing their application domain
while standard design issues are solved with patterns. If you’re working in the API
space, this book will change how you design APIs and how you look at APIs.”

—Erik Wilde, Catalyst at Axway

“The authors have captured design patterns across the API lifecycle, from definition
to design, in an approachable way. Whether you have designed dozens of web APIs or
you are just starting out, this book is a valuable resource to drive consistency and
overcome any design challenge you may face. I highly recommend this book!”

—James Higginbotham
Author of Principles of Web API Design: Delivering value with APIs and
Microservices and Executive API Consultant, LaunchAny

“APIs are everywhere in today’s software development landscape. API design looks
easy but, as anyone who has suffered a poorly designed API will attest, it is a difficult
skill to master and much subtler and more complex than it initially appears. In this
book, the authors have used their long experience and years of research work to cre-
ate a structured body of knowledge about API design. It will help you to understand
the underlying concepts needed to create great APIs and provides a practical set of
patterns that you can use when creating your own APIs. It is recommended for any-
one involved in the design, building, or testing of modern software systems.”

—Eoin Woods, CTO, Endava

Application programming interfaces (API) are among the top priority elements to help
manage many of the trade-offs involved in system design, in particular distributed sys-
tems, which increasingly dominate our software ecosystem. In my experience, this
book removes the complexities in understanding and designing APIs with concepts
accessible to both practicing engineers and those who are just starting their software
engineering and architecting journey. All who aspire to play a key role in system design
should understand the API design concepts and patterns presented in this book.”

—Ipek Ozkaya
Technical Director, Engineering Intelligence Software System
Software Solutions Division
Carnegie Mellon University Software Engineering Institute
Editor-in-Chief 2019–2023 IEEE Software Magazine
“It is my belief that we are entering into an era where API-first design will become
the dominant form of design in large, complex systems. For this reason, Patterns for
API Design is perfectly timed and should be considered essential reading for any
architect.”

—Rick Kazman, University of Hawaii

“Finally, the important topic of API design is addressed systematically! I wish I

would have had this great pattern collection a few years earlier.”
—Dr. Gernot Starke, INNOQ Fellow

“I observed software projects fail because middleware technology hid a system’s

distributed nature from programmers. They designed problematic APIs of a non-
distributed gestalt exercised remotely. This book embraces the required dispersal of
software in an interdependent world and provides timeless advice on designing inter-
faces between its separated parts. The Patterns guide beyond specific middleware
technology and will not only help with creation and understanding but also with
necessary evolution of the interconnected software systems we grow today and in the
future. Those systems not only span the globe for international business, but also
work within our cars, houses, and almost any technology our daily lives depend on.”

—Peter Sommerlad, independent consultant, author of

Pattern-Oriented Software Architecture: A System of Patterns and Security Patterns

“The book Patterns for API Design is the Swiss army knife for software engineers
and architects when it comes to designing, evolving, and documenting APIs. What I
particularly like about the book is that it does not just throw the patterns at the
reader; instead, the authors use realistic examples, provide hands-on architecture
decision support, and exemplify patterns and decisions using a case study. As a
result, their pattern language is very accessible. You can use the book to find solu-
tions for specific problems or browse entire chapters to get an overview of the prob-
lem and solution spaces related to API design. All patterns are well-crafted,
well-named, and peer-reviewed by the practitioner community. It’s a joy.”

—Dr. Uwe van Heesch, Practicing Software Architect and

Former Vice President Hillside Europe
“This comprehensive collection of API patterns is an invaluable resource for soft-
ware engineers and architects designing interoperable software systems. The intro-
duction into API fundamentals and numerous case study examples make it excellent
teaching material for future software engineers. Many of the patterns discussed in
this book are extremely useful in practice and were applied to design the APIs of
integrated, mission-critical rail operations centre systems.”

—Andrei Furda, Senior Software Engineer at Hitachi Rail STS Australia

This page intentionally left blank
Patterns for API Design
 Pearson Addison-Wesley
Signature Series

Visit informit.com/awss/vernon for a complete list of available publications.

The Pearson Addison-Wesley Signature Series provides readers with

practical and authoritative information on the latest trends in modern
technology for computer professionals. The series is based on one
simple premise: great books come from great authors.

Vaughn Vernon is a champion of simplifying software architecture and

development, with an emphasis on reactive methods. He has a unique
ability to teach and lead with Domain-Driven Design using lightweight
tools to unveil unimagined value. He helps organizations achieve
competitive advantages using enduring tools such as architectures,
patterns, and approaches, and through partnerships between business
stakeholders and software developers.

Vaughn’s Signature Series guides readers toward advances in software

development maturity and greater success with business-centric
practices. The series emphasizes organic refinement with a variety
of approaches—reactive, object, and functional architecture and
programming; domain modeling; right-sized services; patterns; and
APIs—and covers best uses of the associated underlying technologies.

Make sure to connect with us!

informit.com/socialconnect
Patterns for API
Design
Simplifying Integration with Loosely
Coupled Message Exchanges

Olaf Zimmermann
Mirko Stocker
Daniel Lübke
Uwe Zdun
Cesare Pautasso

Boston • Columbus • New York • San Francisco • Amsterdam • Cape Town

Dubai • London • Madrid • Milan • Munich • Paris • Montreal • Toronto • Delhi • Mexico City
São Paulo • Sydney • Hong Kong • Seoul • Singapore • Taipei • Tokyo
Cover image: Joshua Small-Photographer / Shutterstock

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where
those designations appear in this book, and the publisher was aware of a trademark claim, the designations have been printed
with initial capital letters or in all capitals.

The authors and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any
kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in
connection with or arising out of the use of the information or programs contained herein.

For information about buying this title in bulk quantities, or for special sales opportunities (which may include electronic
versions; custom cover designs; and content particular to your business, training goals, marketing focus, or branding
interests), please contact our corporate sales department at [email protected] or (800) 382-3419.

For government sales inquiries, please contact [email protected].

For questions about sales outside the U.S., please contact [email protected].

Visit us on the Web: informit.com

Library of Congress Control Number: 2022947404

Copyright © 2023 Pearson Education, Inc.

All rights reserved. This publication is protected by copyright, and permission must be obtained from the publisher prior
to any prohibited reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic,
mechanical, photocopying, recording, or likewise. For information regarding permissions, request forms and the appropriate
contacts within the Pearson Education Global Rights & Permissions Department, please visit www.pearson.com/permissions.

ISBN-13: 978-0-13-767010-9
ISBN-10: 0-13-767010-9

ScoutAutomatedPrintCode
Pearson’s Commitment to Diversity, Equity, and Inclusion
Pearson is dedicated to creating bias-free content that reflects the diversity of all learners. We
embrace the many dimensions of diversity, including but not limited to race, ethnicity, gender,
socioeconomic status, ability, age, sexual orientation, and religious or political beliefs.
Education is a powerful force for equity and change in our world. It has the potential to
deliver opportunities that improve lives and enable economic mobility. As we work with authors
to create content for every product and service, we acknowledge our responsibility to demonstrate
inclusivity and incorporate diverse scholarship so that everyone can achieve their potential
through learning. As the world’s leading learning company, we have a duty to help drive change
and live up to our purpose to help more people create a better life for themselves and to create a
better world.
Our ambition is to purposefully contribute to a world where:

• Everyone has an equitable and lifelong opportunity to succeed through learning.

• Our educational products and services are inclusive and represent the rich diversity of
learners.
• Our educational content accurately reflects the histories and experiences of the learners we
serve.
• Our educational content prompts deeper discussions with learners and motivates them to
expand their own learning (and worldview).

While we work hard to present unbiased content, we want to hear from you about any
concerns or needs with this Pearson product so that we can investigate and address them.

• Please contact us with concerns about any potential bias at https://www.pearson.com/

report-bias.html.
Visit https://ebooknice.com to
discover a wide range of
eBooks across various genres.
Enjoy exclusive deals and
discounts to enhance your
reading experience. Start your
digital reading journey today!
This page intentionally left blank
Contents

Foreword by Vaughn Vernon, Series Editor . . . . . . . . . . . . . . . . . . . . . . . . xvii

Foreword by Frank Leymann . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
About the Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv

Part 1: Foundations and Narratives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1: Application Programming Interface (API) Fundamentals . . . . . . . 3

From Local Interfaces to Remote APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
A Bit of Distribution and Remoting History . . . . . . . . . . . . . . . . . 5
Remote API: Access to Services via Protocol for Integration. . . . . 6
APIs Matter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Decision Drivers in API Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
What Makes an API Successful? . . . . . . . . . . . . . . . . . . . . . . . . . 15
How Do API Designs Differ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
What Makes API Design Challenging? . . . . . . . . . . . . . . . . . . . . 17
Architecturally Significant Requirements . . . . . . . . . . . . . . . . . . 19
Developer Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
A Domain Model for Remote APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Communication Participants . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Endpoints Offer Contracts Describing Operations . . . . . . . . . . . 24
Messages as Conversation Building Blocks . . . . . . . . . . . . . . . . . 24
Message Structure and Representation . . . . . . . . . . . . . . . . . . . . 25
API Contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Domain Model Usage throughout the Book . . . . . . . . . . . . . . . . 27
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 2: Lakeside Mutual Case Study . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Business Context and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
User Stories and Desired Qualities . . . . . . . . . . . . . . . . . . . . . . . 32

xi
xii Contents

Analysis-Level Domain Model . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
System Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
API Design Activities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Target API Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Chapter 3: API Decision Narratives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Prelude: Patterns as Decision Options, Forces as Decision Criteria . . . . 43
Foundational API Decisions and Patterns . . . . . . . . . . . . . . . . . . . . . . . . 45
API Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
API Integration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Documentation of the API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Decisions about API Roles and Responsibilities . . . . . . . . . . . . . . . . . . . 57
Architectural Role of an Endpoint . . . . . . . . . . . . . . . . . . . . . . . 59
Refining Information Holder Roles . . . . . . . . . . . . . . . . . . . . . . . 61
Defining Operation Responsibilities . . . . . . . . . . . . . . . . . . . . . . 66
Selecting Message Representation Patterns . . . . . . . . . . . . . . . . . . . . . . . 70
Flat versus Nested Structure of Representation Elements . . . . . . 71
Element Stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Interlude: Responsibility and Structure Patterns in the
Lakeside Mutual Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Governing API Quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Identification and Authentication of the API Client . . . . . . . . . . 85
Metering and Charging for API Consumption . . . . . . . . . . . . . . 88
Preventing API Clients from Excessive API Usage . . . . . . . . . . . . 90
Explicit Specification of Quality Objectives and Penalties . . . . . 92
Communication of Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Explicit Context Representation . . . . . . . . . . . . . . . . . . . . . . . . . 96
Deciding for API Quality Improvements . . . . . . . . . . . . . . . . . . . . . . . . . 98
Pagination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Other Means of Avoiding Unnecessary Data Transfer . . . . . . . 102
Handling Referenced Data in Messages . . . . . . . . . . . . . . . . . . 107
Decisions about API Evolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Versioning and Compatibility Management . . . . . . . . . . . . . . . 112
Strategies for Commissioning and Decommissioning . . . . . . . . 115
 Contents xiii

Interlude: Quality and Evolution Patterns in the

Lakeside Mutual Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Part 2: The Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Chapter 4: Pattern Language Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 127

Positioning and Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Patterns: Why and How? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Navigating through the Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Structural Organization: Find Patterns by Scope . . . . . . . . . . . 131
Theme Categorization: Search for Topics . . . . . . . . . . . . . . . . . 132
Time Dimension: Follow Design Refinement Phases . . . . . . . . 135
How to Navigate: The Map to MAP . . . . . . . . . . . . . . . . . . . . . 136
Foundations: API Visibility and Integration Types . . . . . . . . . . . . . . . . 137
Pattern: Frontend Integration . . . . . . . . . . . . . . . . . . . . . . . . 138
Pattern: Backend Integration . . . . . . . . . . . . . . . . . . . . . . . . . 139
Pattern: Public API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Pattern: Community API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Pattern: Solution-Internal API . . . . . . . . . . . . . . . . . . . . . . . . 144
Foundation Patterns Summary . . . . . . . . . . . . . . . . . . . . . . . . . 145
Basic Structure Patterns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Pattern: Atomic Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Pattern: Atomic Parameter List . . . . . . . . . . . . . . . . . . . . . . . . 150
Pattern: Parameter Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Pattern: Parameter Forest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Basic Structure Patterns Summary . . . . . . . . . . . . . . . . . . . . . . 157
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Chapter 5: Define Endpoint Types and Operations . . . . . . . . . . . . . . . . . . 161
Introduction to API Roles and Responsibilities. . . . . . . . . . . . . . . . . . . 162
Challenges and Desired Qualities . . . . . . . . . . . . . . . . . . . . . . . 163
Patterns in this Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Endpoint Roles (aka Service Granularity) . . . . . . . . . . . . . . . . . . . . . . . 167
Pattern: Processing Resource . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Pattern: Information Holder Resource . . . . . . . . . . . . . . . . . 176
Pattern: Operational Data Holder . . . . . . . . . . . . . . . . . . . . . 183
Pattern: Master Data Holder. . . . . . . . . . . . . . . . . . . . . . . . . . 190
xiv Contents

Pattern: Reference Data Holder . . . . . . . . . . . . . . . . . . . . . . . 195

Pattern: Link Lookup Resource . . . . . . . . . . . . . . . . . . . . . . . . . 200
Pattern: Data Transfer Resource . . . . . . . . . . . . . . . . . . . . . . . 206
Operation Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Pattern: State Creation Operation . . . . . . . . . . . . . . . . . . . . . 216
Pattern: Retrieval Operation . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Pattern: State Transition Operation . . . . . . . . . . . . . . . . . . . . 228
Pattern: Computation Function . . . . . . . . . . . . . . . . . . . . . . . . 240
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Chapter 6: Design Request and Response Message Representations . . . . . 253
Introduction to Message Representation Design . . . . . . . . . . . . . . . . . 253
Challenges When Designing Message Representations . . . . . . 254
Patterns in this Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Element Stereotypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Pattern: Data Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Pattern: Metadata Element . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Pattern: Id Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Pattern: Link Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Special-Purpose Representations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Pattern:API Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Pattern: Error Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Pattern: Context Representation . . . . . . . . . . . . . . . . . . . . . . 293
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Chapter 7: Refine Message Design for Quality . . . . . . . . . . . . . . . . . . . . . 309
Introduction to API Quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Challenges When Improving API Quality . . . . . . . . . . . . . . . . . 310
Patterns in This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Message Granularity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Pattern: Embedded Entity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Pattern: Linked Information Holder . . . . . . . . . . . . . . . . . . . 320
Client-Driven Message Content (aka Response Shaping) . . . . . . . . . . . 325
Pattern: Pagination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Pattern: Wish List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Pattern: Wish Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
 Contents xv

Message Exchange Optimization (aka Conversation Efficiency) . . . . . 344

Pattern: Conditional Request . . . . . . . . . . . . . . . . . . . . . . . . . 345
Pattern: Request Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Chapter 8: Evolve APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Introduction to API Evolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Challenges When Evolving APIs . . . . . . . . . . . . . . . . . . . . . . . . 358
Patterns in This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Versioning and Compatibility Management . . . . . . . . . . . . . . . . . . . . . 362
Pattern: Version Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Pattern: Semantic Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Life-Cycle Management Guarantees . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Pattern: Experimental Preview. . . . . . . . . . . . . . . . . . . . . . . . . 375
Pattern: Aggressive Obsolescence . . . . . . . . . . . . . . . . . . . . . . 379
Pattern:Limited Lifetime Guarantee . . . . . . . . . . . . . . . . . . . . 385
Pattern: Two in Production. . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Chapter 9: Document and Communicate API Contracts . . . . . . . . . . . . . . 395
Introduction to API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Challenges When Documenting APIs . . . . . . . . . . . . . . . . . . . . 396
Patterns in This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
Documentation Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Pattern: API Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Pattern: Pricing Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Pattern: Rate Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
Pattern: Service Level Agreement . . . . . . . . . . . . . . . . . . . . . . 416
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Part 3: Our Patterns in Action (Now and Then) . . . . . . . . . . . . . . . . . . . . 423

Chapter 10: Real-World Pattern Stories . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Large-Scale Process Integration in the Swiss Mortgage Business . . . . . 426
Business Context and Domain . . . . . . . . . . . . . . . . . . . . . . . . . 426
Technical Challenges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
Role and Status of API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Pattern Usage and Implementation . . . . . . . . . . . . . . . . . . . . . . 429
Retrospective and Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
 Offering and Ordering Processes in Building Construction . . . . . . . . . 438
Business Context and Domain . . . . . . . . . . . . . . . . . . . . . . . . . 438
Technical Challenges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Role and Status of API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Pattern Usage and Implementation . . . . . . . . . . . . . . . . . . . . . . 442
Retrospective and Outlook . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Chapter 11: Conclusion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Short Retrospective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448
API Research: Refactoring to Patterns, MDSL, and More . . . . . . . . . . 449
The Future of APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Final Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Appendix A: Endpoint Identification and Pattern Selection Guides. . . . . . . 453

Appendix B: Implementation of the Lakeside Mutual Case . . . . . . . . . . . . 463

Appendix C: Microservice Domain-Specific Language (MDSL) . . . . . . . . . 471

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499
Foreword by Vaughn Vernon,
Series Editor

My signature series emphasizes organic growth and refinement, which I describe in

more detail below. It only makes sense to start off by describing the organic commu-
nication that I experienced with the first author of this book, Professor Dr. Olaf
Zimmermann.
As I often refer to Conway’s Law of system design, communication is a critical fac-
tor in software development. Systems designs not only resemble the communication
structures of the designers; the structure and assembling of individuals as communica-
tors is just as important. It can lead from interesting conversations to stimulating
thoughts and continue to deliver innovative products. Olaf and I met at a Java User
Group meeting in Bern, Switzerland, in November 2019. I gave a talk on reactive archi-
tecture and programming and how it is used with Domain-Driven Design. Afterward,
Olaf introduced himself. I also met his graduate student and later colleague, Stefan
Kapferer. Together they had organically designed and built the open-source product
Context Mapper (a domain-specific language and tools for Domain-Driven Design).
Our chance meeting ultimately led to this book’s publication. I’ll tell more of this story
after I describe the motivation and purpose of my book series.
My Signature Series is designed and curated to guide readers toward advances in
software development maturity and greater success with business-centric practices.
The series emphasizes organic refinement with a variety of approaches—reactive,
object, as well as functional architecture and programming; domain modeling; right-
sized services; patterns; and APIs—and covers best uses of the associated underlying
technologies.
From here, I am focusing now on only two words: organic refinement.
The first word, organic, stood out to me recently when a friend and colleague
used it to describe software architecture. I have heard and used the word organic in
connection with software development, but I didn’t think about that word as care-
fully as I did then when I personally consumed the two used together: organic
architecture.
Think about the word organic, and even the word organism. For the most part,
these are used when referring to living things, but they are also used to describe inan-
imate things that feature some characteristics that resemble life forms. Organic

xvii
xviii Foreword by Vaughn Vernon, Series Editor

originates in Greek. Its etymology is with reference to a functioning organ of the

body. If you read the etymology of organ, it has a broader use, and in fact organic
followed suit: body organs; to implement; describes a tool for making or doing; a
musical instrument.
We can readily think of numerous organic objects—living organisms—from the
very large to the microscopic single-celled life forms. With the second use of organ-
ism, though, examples may not as readily pop into our mind. One example is an
organization, which includes the prefix of both organic and organism. In this use of
organism, I’m describing something that is structured with bidirectional dependen-
cies. An organization is an organism because it has organized parts. This kind of
organism cannot survive without the parts, and the parts cannot survive without the
organism.
Taking that perspective, we can continue applying this thinking to nonliving
things because they exhibit characteristics of living organisms. Consider the atom.
Every single atom is a system unto itself, and all living things are composed of atoms.
Yet, atoms are inorganic and do not reproduce. Even so, it’s not difficult to think of
atoms as living things in the sense that they are endlessly moving, functioning. Atoms
even bond with other atoms. When this occurs, each atom is not only a single system
unto itself, but becomes a subsystem along with other atoms as subsystems, with
their combined behaviors yielding a greater whole system.
So then, all kinds of concepts regarding software are quite organic in that nonliv-
ing things are still “characterized” by aspects of living organisms. When we discuss
software model concepts using concrete scenarios, or draw an architecture diagram,
or write a unit test and its corresponding domain model unit, software starts to come
alive. It isn’t static because we continue to discuss how to make it better, subjecting it
to refinement, where one scenario leads to another, and that has an impact on the
architecture and the domain model. As we continue to iterate, the increasing value in
refinements leads to incremental growth of the organism. As time progresses, so
does the software. We wrangle with and tackle complexity through useful abstrac-
tions, and the software grows and changes shapes, all with the explicit purpose of
making work better for real, living organisms at global scales.
Sadly, software organics tend to grow poorly more often than they grow well. Even
if they start out life in good health, they tend to get diseases, become deformed, grow
unnatural appendages, atrophy, and deteriorate. Worse still is that these symptoms are
caused by efforts to refine the software that go wrong instead of making things better.
The worst part is that with every failed refinement, everything that goes wrong with
these complexly ill bodies doesn’t cause their death. Oh, if they could just die! Instead,
we have to kill them and killing them requires nerves, skills, and the intestinal fortitude
of a dragon slayer. No, not one, but dozens of vigorous dragon slayers. Actually, make
that dozens of dragon slayers who have really big brains.
 Foreword by Vaughn Vernon, Series Editor xix

That’s where this series comes into play. I am curating a series designed to help
you mature and reach greater success with a variety of approaches—reactive, object,
and functional architecture and programming; domain modeling; right-sized ser-
vices; patterns; and APIs. And along with that, the series covers best uses of the asso-
ciated underlying technologies. It’s not accomplished in one fell swoop. It requires
organic refinement with purpose and skill. I and the other authors are here to help.
To that end, we’ve delivered our very best to achieve our goal.
Now, back to my story. When Olaf and I first met, I offered for him and Stefan to
attend my IDDD Workshop a few weeks later in Munich, Germany. Although nei-
ther were able to break away for all three days, they were open to attend the third and
final day. My second offer was for Olaf and Stefan to use time after the workshop to
demonstrate the Context Mapper tool. The workshop attendees were impressed, as
was I. This led to further collaboration on into 2020. Little did any of us expect what
that year would bring. Even so, Olaf and I were able to meet somewhat frequently to
continue design discussions about Context Mapper. During one of these meetings,
Olaf mentioned his work on API patterns that were provided openly. Olaf showed
me a number of patterns and additional tooling he and others had built around
them. I offered Olaf the opportunity to author in the series. The result is now in
front of you.
I later met on a video call with Olaf and Daniel Lübke to kick off product devel-
opment. I have not had the chance to spend time with the other authors—Mirko
Stocker, Uwe Zdun, Cesare Pautasso—but I was assured of the team’s quality given
their credentials. Notably, Olaf and James Higginbotham collaborated to ensure the
complementary outcome of this book and Principles of Web API Design, also in this
series. As an overall result, I am very impressed with what these five have contributed
to the industry literature. API design is a very important topic. The enthusiasm
toward the book’s announcement proves that it is right in the topic’s sweet spot. I am
confident that you will agree.
—Vaughn Vernon, series editor
Visit https://ebooknice.com to
discover a wide range of
eBooks across various genres.
Enjoy exclusive deals and
discounts to enhance your
reading experience. Start your
digital reading journey today!
This page intentionally left blank
Foreword by Frank Leymann

APIs are everywhere. The API economy enables innovation in technology areas,
including cloud computing and the Internet of Things (IoT), and is also a key ena-
bler of digitalization of many companies. There hardly is any enterprise application
without external interfaces to integrate customers, suppliers, and other business
partners; solution-internal interfaces decompose such applications into more man-
ageable parts, such as loosely coupled microservices. Web-based APIs play a promi-
nent role in these distributed settings but are not the only way to integrate remote
parties: queue-based messaging channels as well as publish/subscribe-based channels
are widely used for backend integration, exposing APIs to message producers and
consumers. gRPC and GraphQL have gained a lot of momentum as well. Thus, best
practices for designing “good” APIs are desirable. Ideally, API designs persist across
technologies and survive when those change.
Patterns establish a vocabulary for a problem-solution domain, finding a balance
between being abstract and concrete, which gives them both timelessness and rele-
vance today. Take Enterprise Integration Patterns by Gregor Hohpe and Bobby Woolf
from the Addison Wesley Signature Series as an example: I have been using it in
teaching and industry assignments since my time as lead architect of the IBM MQ
family of products. Messaging technologies come and, sometimes, go—but the mes-
saging concepts such as Service Activator and Idempotent Receiver are here to stay. I
have written cloud computing patterns, IoT patterns, quantum computing patterns,
even patterns for patterns in digital humanities myself. And Martin Fowler’s Patterns
of Enterprise Application Architecture, also from the Addison Wesley Signature
Series, gives us the Remote Façade and the Service Layer. Hence, many parts of the
overall design space of distributed applications are covered well in this literature—
but not all. Therefore, it is great to see that the API design space is now supported by
patterns too, the request and response messages that travel between API client and
API provider in particular.
The team who wrote this book is a great mix of architects and developers com-
posed of deeply experienced industry professionals, leaders in the patterns commu-
nity, and academic researchers and lecturers. I have been working with three of the
authors of this book for many years and have been following their MAP project since
its inception in 2016. They apply the pattern concept faithfully: Each pattern text
follows a common template that takes us from a problem context, including design
forces, to a conceptual solution. It also comes with a concrete example (often

xxi
xxii Foreword by Frank Leymann

RESTful HTTP). A critical discussion of pros and cons resolves the initial design
forces and closes with pointers to related patterns. Many of the patterns went
through shepherding and writers workshops at pattern conferences, which helped to
incrementally and iteratively improve and harden them over several years, capturing
collective knowledge as a result from this process.
This book provides multiple perspectives on the API design space, from scoping
and architecture to message representation structure and quality attribute-driven
design to API evolution. Its pattern language can be navigated via different paths,
including project phases and structural elements such as API endpoint and opera-
tion. As in our Cloud Computing Patterns book, a graphical icon for each pattern
conveys its essence. These icons serve as mnemonics and can be used to sketch APIs
and their elements. The book takes a unique and novel step in providing decision
models that collect recurring questions, options, and criteria regarding pattern
applications. They provide stepwise, easy-to-follow design guidance without over-
simplifying the complexities inherent to API design. A stepwise application to a sam-
ple case makes the models and their advices tangible.
In Part 2, the patterns reference, application and integration architects will find
the coverage of endpoint roles such as Processing Resource and operation responsi-
bilities such as State Transition Operation useful to size APIs adequately and make
(cloud) deployment decisions. State matters, after all, and several patterns make
state management behind the API curtain explicit. API developers will benefit from
the careful consideration given to identifiers (in patterns such as API Key and Id Ele-
ment), several options for response shaping (for instance, with Wish Lists and a Wish
Template that abstracts from GraphQL), and pragmatic advice on how to expose
metadata of different kinds.
I have not seen life-cycle management and versioning strategies captured in pattern
form in other books so far. Here, we can learn about Limited Lifetime Guarantees and
Two in Production, two patterns very common in enterprise applications. These evolu-
tion patterns will be appreciated by API product owners and maintainers.
In summary, this book provides a healthy mix of theory and practice, containing
numerous nuggets of deep advice but never losing the big picture. Its 44 patterns,
organized in five categories and chapters, are grounded in real-world experience and
documented with academic rigor applied and practitioner-community feedback
incorporated. I am confident that these patterns will serve the community well,
today and tomorrow. API designers in industry as well as in research, development,
and education related to API design and evolution can benefit from them.

—Prof. Dr. Dr. h. c. Frank Leymann, Managing Director

Institute of Architecture of Application Systems
University of Stuttgart
Preface

This introduction to our book covers the following:

• The context and the purpose of the book—its motivation, goals and scope.
• Who should read the book—our target audience with their use cases and
information needs.
• How the book is organized, with patterns serving as knowledge vehicles.

Motivation
Humans communicate in many different languages. The same holds for software.
Software not only is written in various programming languages but also communi-
cates via a plethora of protocols (such as HTTP) and message exchange formats
(such as JSON). HTTP, JSON, and other technologies operate every time somebody
updates their social network profile, orders something in a Web shop, swipes their
credit card to purchase something, and so on:

• Application frontends, such as mobile apps on smartphones, place requests

for transaction processing at their backends, such as purchase orders in online
shops.
• Application parts exchange long-lived data such as customer profiles or product
catalogs with each other and with the systems of business partners, customers,
and suppliers.
• Application backends provide external services such as payment gateways or
cloud storage with data and metadata.

The software components involved in these scenarios—large, small, and

in-between—talk to others to achieve their individual goals while jointly serving end
users. The software engineer’s response to this distribution challenge is application
integration via application programming interfaces (APIs). Every integration
scenario involves at least two communication parties: API client and API provider.

xxiii
xxiv Preface

API clients consume the services exposed by API providers. API documentation gov-
erns the client-provider interactions.
Just like humans, software components often struggle to understand each other
when they communicate; it is hard for their designers to decide on an adequate size and
structure of message content and agree on the best-suited conversation style. Neither
party wants to be too quiet or overly talkative when articulating its needs or responding
to requests. Some application integration and API designs work very well; the involved
parties understand each other and reach their goals. They interoperate effectively and
efficiently. Others lack clarity and thereby confuse or stress participants; verbose mes-
sages and chatty conversations may overload the communication channels, introduce
unnecessary technical risk, and cause extra work in development and operations.
Now, what distinguishes good and poor integration API designs? How can API
designers stimulate a positive client developer experience? Ideally, the guidelines for
good integration architectures and API designs do not depend on any particular
technology or product. Technologies and products come and go, but related design
advice should stay relevant for a long time. In our real-world analogy, principles such
as those of Cicero’s rhetoric and eloquence or Rosenberg’s in Nonviolent Communi-
cation: A Language of Life [Rosenberg 2002] are not specific to English or any other
natural language; they will not go out of fashion as natural languages evolve. Our
book aims to establish a similar toolbox and vocabulary for integration specialists
and API designers. It presents its knowledge bits as patterns for API design and evo-
lution that are eligible under different communication paradigms and technologies
(with HTTP- and JSON-based Web APIs serving as primary sources of examples).

Goals and Scope

Our mission is to help overcome the complexity of designing and evolving APIs
through proven, reusable solution elements:

How can APIs be engineered understandably and sustainably, starting from

stakeholder goals, architecturally significant requirements, and already
proven design elements?

While much has been said and written about HTTP, Web APIs, and integration
architectures in general (including service-oriented ones), the design of individual
API endpoints and message exchanges has received less attention so far:

• How many API operations should be exposed remotely? Which data should be
exchanged in request and response messages?
 Preface xxv

• How is loose coupling of API operations and client-provider interactions ensured?

• What are suitable message representations: flat or hierarchically nested ones?
How is agreement reached on the meaning of the representation elements so
that these elements are processed correctly and efficiently?
• Should API providers be responsible for processing data provided by their cli-
ents, possibly changing the provider-side state and connecting to backend sys-
tems? Or should they merely provide shared data stores to their clients?
• How are changes to APIs introduced in a controlled way that balances extensi-
bility and compatibility?

The patterns in this book help answer these questions by sketching proven solu-
tions to specific design problems recurring in certain requirements contexts. Focus-
ing on remote APIs (rather than program-internal ones), they aim at improving the
developer experience on both the client side and the provider side.

Target Audience
This book targets intermediate-level software professionals striving to improve their
skills and designs. The presented patterns primarily aim at integration architects,
API designers, and Web developers interested in platform-independent architectural
knowledge. Both backend-to-backend integration specialists and developers of APIs
supporting frontend applications can benefit from the knowledge captured in the
patterns. As we focus on API endpoint granularity and the data exchanged in mes-
sages, additional target roles are API product owner, API reviewer, and cloud tenant
and provider.

This book is for you if you are a medium-experienced software engineer (such
as developer, architect, or product owner) already familiar with API funda-
mentals and want to improve your API design capabilities, including message
data contract design and API evolution.

Students, lecturers, and software engineering researchers may find the patterns
and their presentation in this book useful as well. We provide an introduction to API
fundamentals and a domain model for API design to make the book and its patterns
understandable without first having to read a book for beginners.
xxvi Preface

Knowing about the available patterns and their pros and cons will improve profi-
ciency regarding API design and evolution. APIs and the services they provide will be
simpler to develop, consume, and evolve when applying patterns from this book
suited for a particular requirements context.

Usage Scenarios
Our objective is to make API design and usage a pleasant experience. To that end,
three main use cases for our book and its patterns are as follows:
1. Facilitate API design discussions and workshops by establishing a common
vocabulary, pointing out required design decisions, and sharing available
options and related trade-offs. Empowered by this knowledge, API providers
are enabled to expose APIs of quality and style that meet their clients’ needs,
both short term and long term.
2. Simplify API design reviews and speed up objective API comparisons so that
APIs can be quality assured—and evolved in a backward-compatible and
extensible way.
3. Enhance API documentation with platform-neutral design information so that
API client developers can grasp the capabilities and constraints of provided
APIs with ease. The patterns are designed to be embeddable into API contracts
and observable in existing designs.

We provide a fictitious case study and two real-world pattern adoption stories to
demonstrate and jumpstart this pattern usage.
We do not expect readers to know any particular modeling approach, design tech-
nique, or architectural style already. However, such concepts—for instance, the
Align-Define-Design-Refine (ADDR) process, domain-driven design (DDD), and
responsibility-driven design (RDD)—have their roles to play. They are reviewed
briefly in Appendix A.

Existing Design Heuristics (and Knowledge Gaps)

You can find many excellent books that provide deep advice on specific API technol-
ogies and concepts. For instance, the RESTful Web Services Cookbook [Allamaraju
2010] explains how to build HTTP resource APIs—for example, which HTTP
method such as POST or PUT to pick. Other books explain how asynchronous mes-
saging works in terms of routing, transformation, and guaranteed delivery [Hohpe
2003]. Strategic DDD [Evans 2003; Vernon 2013] can get you started with API
 Preface xxvii

endpoint and service identification. Service-oriented architecture, cloud computing,

and microservice infrastructure patterns have been published. Structuring data stor-
ages (relational, NoSQL) is also documented comprehensively, and an entire pattern
language for distributed systems design is available as well [Buschmann 2007].
Finally, Release It! extensively covers design for operations and deployment to pro-
duction [Nygard 2018a].
The API design process, including goal-driven endpoint identification and opera-
tion design, is also covered well in existing books. For instance, Principles of Web
API Design: Delivering Value with APIs and Microservices [Higginbotham 2021]
suggests four process phases with seven steps. The Design of Web APIs [Lauret 2019]
proposes an API goal canvas, and Design and Build Great Web APIs: Robust, Relia-
ble, and Resilient [Amundsen 2020] works with API stories.
Despite these invaluable sources of design advice, the remote API design space
still is not covered sufficiently. Specifically, what about the structures of the request
and response messages going back and forth between API client and provider? Enter-
prise Integration Patterns [Hohpe 2003] features three patterns representing message
types (event, command, and document message) but does not provide further details
on their inner workings. However, “data on the outside,” exchanged between sys-
tems, differs from “data on the inside” that is processed program-internally [Helland
2005]. There are significant differences between the two types of data in terms of
their mutability, lifetime, accuracy, consistency, and protection needs. For instance,
increasing a local stock-item counter internal to an inventory system probably
requires somewhat less architecture design than product pricing and shipment infor-
mation that is exchanged between manufacturers and logistics companies jointly
managing a supply chain via remote APIs and messaging channels.
Message representation design—data on the outside [Helland 2005] or the “Pub-
lished Language” pattern [Evans 2003] of an API—is the main focus area of this
book. It closes the knowledge gaps regarding API endpoint, operation, and message
design.

Patterns as Knowledge Sharing Vehicles

Software patterns are sophisticated knowledge-sharing instruments with a track
record of more than 25 years. We decided for the pattern format to share API design
advice because pattern names aim at forming a domain vocabulary, a “Ubiquitous
Language” [Evans 2003]. For instance, the enterprise integration patterns have
become the lingua franca of queue-based messaging; these patterns were even imple-
mented in messaging frameworks and tools.
xxviii Preface

Patterns are not invented but are mined from practical experience and then hard-
ened via peer feedback. The patterns community has developed a set of practices to
organize the feedback process; shepherding and writers’ workshops are two particu-
larly important ones [Coplien 1997].
At the heart of each pattern is a problem-solution pair. Its forces and the discus-
sion of consequences support informed decision making, for instance, about desired
and achieved quality characteristics—but also about the downsides of certain
designs. Alternative solutions are discussed, and pointers to related patterns and
possible implementation technologies complete the picture.
Note that patterns do not aim at providing complete solutions but serve as
sketches to be adopted and tailored for a particular, context-specific API design. In
other words, patterns are soft around their edges; they outline possible solutions but
do not provide blueprints to be copied blindly. How to adopt and realize a pattern to
satisfy project or product requirements remains the responsibility of API designers
and owners.
We have been applying and teaching patterns in industry and academia for a long
time. Some of us have written patterns for programming, architecting, and integrat-
ing distributed application systems and their parts [Voelter 2004; Zimmermann
2009; Pautasso 2016].
We found the pattern concept to be well suited for the usage scenarios stated ear-
lier under “Goals and Scope” and “Target Audience.”

Microservice API Patterns

Our pattern language, called Microservice API Patterns (MAP), provides compre-
hensive views on API design and evolution from the perspective of the messages
exchanged when APIs are exposed and consumed. These messages and their pay-
loads are structured as representation elements. The representation elements differ
in their structure and meaning because API endpoints and their operations have dif-
ferent architectural responsibilities. The message structures strongly influence the
design time and runtime qualities of an API and its underlying implementations; for
instance, few large messages cause network and endpoint workloads (such as CPU
consumption and network bandwidth usage) that differ from those caused by many
small messages. Finally, successful APIs evolve over time; the changes over time have
to be managed.
We chose the metaphor and acronym MAP because maps provide orientation and
guidance, just as pattern languages do; they educate their readers on the options
available in an abstract solution space. APIs themselves also have a mapping nature,
as they route incoming requests to the underlying service implementations.
Random documents with unrelated
content Scribd suggests to you:
lines. Downright fraud is possible, as in the concealment or false
weighing of dutiable articles, the publication of false statements
regarding the financial condition of fiduciary institutions, the covering
up of defects in tenement house building, and so on. Practices of this
character are extremely dangerous, however, as they are subject to
detection and consequent punishment by the first more than
ordinarily inquisitive inspector. Criminal chances are materially
improved by the bribery of officials who are thus bound to
concealment both by money interest and their own fear of exposure.
Vigilant and honest administration of the laws and the infliction of
sufficient penalties, particularly if they involve the imprisonment of
principals, may be trusted to reduce such practices to a minimum.
There are, however, other and more open methods of attack upon
the regulation of business by the state. Appeal may be made to the
courts in the hope that laws of this character may be declared
unconstitutional. Business interests may also seek their repeal or
amendment at the hands of the legislature. No one who accepts the
fundamental principles of our government can quarrel with either of
these two modes of procedure. While doubtless intended to secure
the public interest, attempts to regulate industry by the state may in
given cases really defeat this end. And the latter likelihood would be
increased almost to the point of certainty if legitimate protests from
the businesses affected were stifled. On the other hand attempts
may be made by business interests to influence courts or
legislatures corruptly. Assuming that the honesty of all the
departments of government would be proof against such attempts
there is still another possibility. A business affected by some form of
state regulation may endeavour to call to its aid the influence of
party. This final method of procedure may also be conducted in a
perfectly legitimate fashion. Public sentiment may be honestly
converted to the view that the amendment or repeal of the law, as
demanded by the business interest, is also in the interest of the state
as a whole. On the other hand the effort may be made, either by
large contributions to campaign funds, or by other still more
objectionable means, to enlist the support of party regardless of the
public welfare. Carrying out these various methods of procedure to
their logical conclusion brings us, therefore, face to face with the
question which underlies the whole fabric of political corruption,
namely how shall our party organisations be supported and
financed?
Reserving this issue for subsequent discussion, certain general
features of the reaction of industry against state regulation must be
noted as of immense importance. Black as it is corruption after all is
a mere incident in this struggle. The broad lines of development
which the Republic will follow in the near future would seem to
depend largely upon the outcome of this great process. Certain
social prophets tell us insistently that there are but two possibilities: if
the state wins the upper hand the inevitable result will be socialism; if
on the other hand business triumphs we must resign ourselves to a
more or less benevolent financial oligarchy. Imagination is not
lacking to embellish or render repulsive this pair of alternatives. From
Plato to Herbert George Wells all social prophets have been thus
gifted with the power of depicting finely if not correctly the minutiæ of
the world as it is to be. Time, the remorseless confuter of all earlier
forecasters of this sort, has shown them to be singularly lacking in
the ability to anticipate the great divergent highways of development,
—sympodes in Ward’s phrase,—which have opened up before the
march of human progress and determined the subsequent lines of
movement. So it may well be in the present case. The social futures,
one or the other of which we are bidden by present day prophets to
choose, are like two radii of a circle. They point in very different
directions, it is true, but between them are many possible yet
uncharted goals. And if social development may be likened to
movement in three instead of only two dimensions the lines open to
the future are enormously more divergent than our seers are wont to
conceive. Employing a less mathematical figure, prophecy usually
proceeds from the assumption that cataclysmic changes are
immediately impending. Otherwise, by the way, the prophets would
utterly fail to attract attention. But this presupposes an extremely
plastic condition of society. If social structures, however, really are so
plastic, they may then be remoulded not into one or two forms
merely, but into many other forms conceivable or inconceivable at
the present time. Current and widely accepted forecasts to the
contrary, therefore, one may still venture to doubt that our through
ticket to 1950 or 2000 a.d. is inscribed either “socialism” or “financial
oligarchy,” and stamped “non-transferable.”
Whatever the future may bring forth faith has not yet been lost in
the efficacy of state regulation. It is certainly within the bounds of
possibility that some working balance between government and
industry may be established through this means which will continue
indefinitely. As late as 1870, according to Mr. Dicey, individualistic
opinions dominated English law-making thought.[57] Reaction from
the doctrine of laisser faire was, if anything, even later in the United
States. For a considerable period after the turning point had been
passed measures of state regulation were weakened by survivals of
old habits of thought. Even to-day the period of construction and
extension along the line of state regulation seems far from finished.
Certain inevitable errors have required correction, but no major
portion of the system has been abandoned. Further progress should
be made easier by accumulating experience and precedents.
It is significant of the temper of the American people on this
question that an increasing number of the great successes of our
political life are being made by the men who have shown themselves
strongest and most resourceful in correcting the abuses of business.
Under present conditions no public man suspected of weakness on
this issue has the remotest chance of election to the presidency or to
the governorship of any of our larger states. On the purely
administrative side of the system of state regulation new and more
powerful agencies,—such as the Bureau of Corporations and the
various state Public Service Commissions,—have been devised
recently to grapple with the situation.
Considering the extreme importance of the work which such
agencies have to perform it is improbable that either their position, or
the position of government in general, is as yet sufficiently strong
with reference to corporate interests. Under modern conditions
success in business means very large material rewards. Important
as are industry and commerce, however, certain parts of the work
which the state is now performing are, from the social point of view,
immensely more valuable. The commonweal requires that our best
intellect be applied to these tasks. Any condition which favours the
drafting of our ablest men from the service of the state into the
service of business is a point in favour of the latter wherever the
conflict between them is joined. Yet not infrequently we witness the
promotion of judges to attorneyships for great corporations, the
translation of men who have won their spurs in administrative
supervision of certain kinds of business to high managerial positions
in these same businesses. As long as our morals remain as
mercenary as those of a Captain Dugald Dalgetty there may seem to
be little to criticise in such transactions. Doubtless loyalty is shown
by the men concerned to the government, their original employer,
and to the corporation, their ultimate employer. If, however, there is
to be an exchange of labourers between these fields it would be
vastly better for the state if the man who had succeeded brilliantly in
business should normally expect promotion to high governmental
position. As things are at present the glittering prizes known to be
obtained by ex-government officials who have gone into corporation
service cannot have the most favourable effect upon the minds and
activities of officials remaining in public positions requiring them to
exercise supervision over business activities.
It is high time that there should be a reversal of policy in this
connection. We need urgently greater security of tenure, greater
social esteem, much higher salaries, and ample retiring pensions for
those public officials who are on the fighting line of modern
government. Incomes as large as those of our insurance presidents
or trust magnates are not needed, although in many cases they
would be much more richly deserved. There is recompense which
finer natures will always recognise in the knowledge that they are
performing a vitally important public work. In spite of the loss which
political corruption causes the state it is probably more than made up
by the devoted, and in part unrequited, work of its good servants.
Still the labourer is worthy of his hire. It is both deplorable and
disastrous that the current rewards of good service should be so
meagre while the rewards of betrayal are so large.[58]
But it may be objected that public sentiment in a democracy will
not support high salaries even for the most important public services,
that democracies notoriously remunerate their higher officials very
much less adequately than monarchies. The time is ripe, however,
for challenging this attitude. As long as government work is looked
upon as a dull, soulless, and not extremely useful routine, popular
opposition to high salaries is not only comprehensible but
praiseworthy. Once convinced of the value of certain services,
however (and there is plentiful opportunity to do this), it is doubtful if
self-governing peoples will show themselves less intelligent than
kings. Even now engineers directing great and unusual public
undertakings are frequently paid larger salaries than high officers of
government charged with the execution of ordinary functions.
Recognition of the importance of the work of the specialist is much
more common now than formerly. The development of science and
large scale industry is daily enforcing this lesson. As regards the
unwillingness of democracy to pay well, a change that has recently
come over the policy of certain labour unions is worth noting. Instead
of ordering strikes they have on occasion taken a lesson from the
procedure of their employers, and resorted to the courts for the
redress of grievances. And in doing so they have called in the very
ablest lawyers they could find, paying the latter out of the funds of
the union fees as large as they could have earned on the opposing
side. A similar illustration is afforded by the policy of the Social-
democratic party in Germany which for a considerable period has
recognised and met the necessity of remunerating its leaders in
editorial, parliamentary, and propagandist work at professional rates
far higher than the average wages received by the party rank and
file.[59] Demos may despise aristocracy of birth but he is perhaps not
so incapable of comprehending the aristocracy of service as many of
his critics suppose.

By the system of regulation, as we have seen, government is

brought into close contact with business along many lines. But the
state is also one of the largest sellers and buyers in the markets of
the world, and as such has many other intimate points of contact
with economic affairs. Like any individual or corporation under the
same circumstances it is liable to be victimised by practices
designed fundamentally to make it sell cheaply or buy dearly,—both
to the advantage of corrupt outside interests. Franchise grabbing is
perhaps the most magnificent single example of the difficulties the
state encounters when it appears as a vendor. Popular ignorance of
the real nature of such valuable rights has been responsible for
enormous losses on this score. A city which for any reason had to
dispose of a parcel of land would find itself safeguarded in some
measure by the fact that a large number of its citizens were familiar
with real estate values and methods. Knowledge of intangible
property is very much less common. There has been a great deal of
effective educational work along this line, however, and that
community is indeed backward which at the present time does not
understand perfectly that perpetual franchises without proper
safeguards of public interests are fraudulent on their face.
Administrative agencies such as were referred to in connection with
business regulation, and particularly public service commissions, are
doing extremely valuable work in cutting down the possibilities of
franchise corruption. The grabbing of alleys, the seizure of water
fronts, and the occupation of sidewalks are minor forms of the same
sort of evil which can no longer be practised with the impunity
characteristic of the good old free and easy days of popular
ignorance and carelessness.
In disposing of its public domain, although here, of course, the
price obtained was not the major consideration on the part of the
government, notorious cases of corruption were of common
occurrence. Recent developments, particularly in connection with
timber, mineral, and oil lands, reveal the stiffer attitude which the
public and the government are taking on this question. Time was
also when deposits of public funds yielded little or no interest to cities
and counties. At bottom such loan transactions were sales, i.e., the
sale of the temporary use of public monies. Quite commonly
treasurers were in the habit of considering themselves responsible
for the return of capital sums only, and any interest received was
regarded as a perquisite of office. The system had all the support of
tradition and general usage; it was frequently practised with no effort
at concealment and without protest on moral or business grounds.
Nowadays its existence would be regarded as a sign of political
barbarism, and would furnish opportunity for charges of corruption
about which effective reform effort would speedily gather.
The element of selling is not of major importance in many services
performed by the state which nevertheless require constant watching
in order to prevent corrupt misuse. Efforts to use the mails
improperly are continually being made by get-rich-quick schemes,
swindlers, gamblers, and touts of all descriptions. Crop reports are
furnished without charge, but extraordinary precautions are
necessary to prevent them from leaking out.
Instances such as the foregoing also serve to illustrate the point
that any extension of the functions of government results in an
enlargement of the opportunities for political corruption. Government
railways, for example, would afford venal public officials many
crooked opportunities (as e.g., for false billing, charges, and
discrimination) which do not now exist as direct menaces to public
administrative integrity. Private management of railways, however,
has not been so free from such evils as to be able to use this
argument effectively against nationalisation. Municipalities selling
water, gas, or electricity, are notoriously victimised on a large scale
by citizens whose self-interest as consumers overcomes all thought
of civic duty or common honesty.[60] There is one other closely
related phenomenon connected with the extension of the economic
functions of government which will perhaps not so readily be thought
of as corrupt, and which yet deserves consideration from that point
of view. Public service enterprises under government ownership and
management are always exposed to what some writers stigmatise as
“democratic finance,”—that is strong popular pressure to reduce
rates. Cost of production and the general financial condition of a
given city may make the reduction of the prices charged for water,
electricity, or gas, frankly contrary to public policy. Yet the self-
interest of the consumer suggests the use of his vote and political
influence to compel such reductions. Of course his action is not
consciously corrupt, but it has every other characteristic feature of
this evil.
 The state is a much larger buyer than seller, and manifold are the
possibilities of malpractice in connection with its enormous
purchases of land, materials, supplies, and labour. Yet nothing in our
contemporary political life is more marvellous than the light-hearted
indifference with which the public regards the voting and expenditure
of sums running into the millions. We recall vaguely that the great
constitutional issues of English history were fought out on fiscal
grounds, but we find the budget of our own city a deadly bore. We
rise in heated protest whenever the tax rate is advanced by a
fraction of a mill, but we regard with indifference the new forms either
of necessary expenditure or needless extravagance which make
such increases inevitable. There is one general advantage which
state buying has over state selling, however. A great many of the
purchases of government are made in competitive markets where
fair price rates are ascertainable with comparative ease. Even large
public contracts such as for erecting public buildings or for road
construction are usually resolvable into a number of comparatively
simple processes and purchases. Of course there are exceptions, as
for example government contracts with railroad companies for
carrying mail. But as a rule the ordinary purchasing operations of the
state are simpler and more easily comprehensible than such acts of
sale as franchise grants,—to mention the one of most importance
from the view point of possible corruption. It is precisely at this
vulnerable point on the buying side of governmental operations that
the New York Bureau of Municipal Research has struck home. With
a skill that amounts to positive genius this voluntary agency has
placed before the people the ruling market prices and the
enormously higher prices actually paid by officials for public supplies.
Taking the purchasing departments of our best organised private
corporations as a model it has drawn practical plans for the
installation of similar methods as part of our municipal machinery.
Equipped with field glasses and mechanical registering devices its
agents have kept tab upon the flaccid activities of labourers in the
public service and have contrasted the long distance results thus
obtained with the suddenly energised performances of the same
men when they knew themselves to be under observation. It has co-
operated quietly and effectively with all willing officials in improving
the methods of work in their offices, in installing more logical
accounting systems and better methods of recording work done; and
it has fought effectively, with the penalty of discharge by the
Governor in two cases, those officials who were not amenable to
proper corrective influences. And finally the Bureau has attacked the
city budget and has even succeeded in making that dry and
formidable document the object of active and intelligent public
interest. Yet the cost of the Bureau’s work has been out of all
proportion small in comparison with the benefits obtained. “Less than
$30,000 was spent in 1908 in securing for four million people the
beginnings of a method of recording work done when done, and
money spent when spent, which will henceforth make inefficiency
harder than efficiency, and corruption more difficult than honesty.”[61]
It is extremely gratifying to note the widespread interest which this
work is arousing. Philadelphia and Cincinnati have established
bureaus under the supervision of the parent organisation, and other
cities are earnestly considering similar action. There would seem to
be ample opportunity for the employment of the same sort of agency
in connection with our state governments, and possibly in certain
fields of national administration. Altogether it is by far the most
noteworthy recent effort to stamp out governmental inefficiency and
corruption. Other efforts are being made to the same end,
particularly where extravagance is concerned. In many cities
business men’s clubs, improvement associations, and taxpayers’
leagues, are watching expenditure as it has never been watched
before. Public officials have co-operated loyally in a number of
cases. Occasional discoveries have been made of safeguards and
powers in the law which had been long forgotten or unused. The
progress of uniform bookkeeping is rapid and highly significant in this
connection. Aided largely by the latter development census reports,
particularly the special issues dealing with statistics of cities of over
30,000 inhabitants, are making it possible to compare municipalities
on strictly quantitative lines as to the cost and efficiency of various
services. Altogether we are developing a new financial alertness and
intelligence that should materially cut down various forms of political
inefficiency and corruption, particularly on the purchasing side of
governmental operations. It is not too much to say that the methods
by which these results are to be effected are either at hand or
capable of being worked out on demand. The question now is simply
one of funds and the training of specialists to do the work.

Efforts by the state to regulate or suppress vice and crime bring

about reactions on the part of the interests affected not unlike those
which follow from the attempt to regulate legitimate business.[62] The
corrupt practices thus occasioned are among the commonest and
most objectionable that society has to contend with. Very large
money returns in the aggregate are obtainable by political
organisations which protect vice. It is doubtful, however, whether
such sources of income are ordinarily so productive financially as the
various corrupt relationships between business and politics
described above. On the other hand the alliance between politics
and the underworld has the advantage, from an unmoral point of
view, that it yields not only money but also strong support at the
polls. And as some of the voters whose support is thus secured may
be depended upon for work as repeaters, ballot-box staffers, and
thugs, the net political power which they wield is much greater than
their number alone would indicate. There is one other important
difference between the corruption arising from the attempt to
regulate legitimate business and that which arises from the
regulation of vice. In the former case a “deal” can frequently be
consummated between two principals, the leader of a centralised
business interest on the one hand and the leader of a centralised
political organisation on the other. Something of the secrecy and the
binding personal obligation of a “gentleman’s agreement” are thus
obtained. Of course to carry out the compact the political leader must
control the action of his dependents in public office, but the latter,
whatever they may suspect, know nothing definite about the
agreement into which the boss has entered. The protection of vice
cannot be managed by so small a number of conspirators.
Compliance by the whole police force with orders from the “front” is
necessary. Every patrolman knows what is going on when he is told
that he must not molest dives, gambling hells, or brothels. Members
of the force may or may not be used to collect protection money and
pass it “higher up,” but since there are many establishments which
must pay tribute the employment of a considerable corps of
collectors is necessary. In any event the number of those who have
knowledge amounting to legal evidence is likely to be much larger in
the case of the protection of vice than in the case, for example, of a
corrupt franchise grant. Exposure either by some disgruntled police
officer or by some overtaxed purveyor of vice is likely to come at any
moment.
When revelations of this kind are made the moral uprising which
follows seldom lacks force. Cynics may sneer at such popular
manifestations as paroxysms of virtue, but practical political leaders
are not likely to underestimate the damage which they are capable of
inflicting. Even if the machine emerges comparatively unharmed
from such a period of attack the heads of some of the leaders are
likely to fall before the popular fury. Remembering Fernando Wood’s
caution about the necessity of “pandering a little to the moral
element in the community,” farsighted bosses are therefore more
and more inclined to limit their operations in the field of vice
protection and to seek support from their relations with legitimate
business interests. If this process is carried on further, as now seems
likely, the general problem we are considering will be simplified by
the reduction to a minimum of corruption by the vicious element,
although, of course, we would still have on our hands the large
question of corruption in the interests of otherwise legitimate
business.
With all their mistakes and wasted energy moral uprisings will help
this development materially. After a “spasm” things seldom fall back
into the lowest depths of their former state. We need more frequent
spasms, at least until we shall have learned to live continuously and
steadily on a higher plane. The gravest evil of the present
intermittent situation would seem to be that in our occasional fits of
indignation we write requirements into the law which, considering the
prevalence of minor vicious habits among large masses of the
people, are impossible of execution. One of the lessons which we
have learned in attempting to regulate business is that legislation of
this sort must be supplemented by special administrative agencies if
it is to have any effect whatever. Admirable child labour laws, for
example, remain absolutely futile without labour commissioners and
a force of inspectors created particularly to see them enforced. Yet in
the regulation of vice we rush on heedlessly piling one new duty after
another upon an already overburdened and underpaid police force.
As a consequence its chiefs become habituated to the idea that they
can exercise discretion as to what laws are to be enforced and what
laws may with impunity be neglected. Usually the police decision of
such questions is that crime must be dealt with vigilantly and
severely, vice, on the other hand, with large tolerance. No better
situation could be devised for the schemes of corruptionists.
Moreover the latter are materially aided in their nefarious work by the
high standards and the severe penalties which the moral element
has written into the law. Using these as clubs the corrupt politician
can extort much larger contributions than would otherwise be
possible. There are only two ways in which this situation may be
met. Either we must reduce our too ambitious programmes for the
regulation of vice, or we must strengthen our police forces until they
are adequate to meet the demands placed upon them.
In whatever way this question may be decided there is ample
ground for demanding the application of the most thoroughgoing civil
service reform rules to our police establishments. It is well known
that the rank and file of our police forces despise the dirty work
forced upon them by the political wretches “higher up.” No man
capable of the heroic deeds which are commonplace in the annals of
the police service rings the doors of bawdy houses and collects a
tithe from the sorrowful wages of shame except under the
compulsion of the sternest bread and butter necessity. Usually it is
necessary to select the yellow dogs of the force for this particular
devil’s work, and the promotion of such creatures for their pliancy is
a stench in the nostrils of their honest comrades. If one doubts that
this is the real spirit of the police force let him consider the character
of the fire departments of nearly all of our cities. The men in the latter
service are chosen from the same class, face dangers of the same
magnitude, and receive wages of about the same amount as
policemen. In the main they deserve and receive high praise for their
efficiency and honesty. It is true that they are not exposed to the
corrupt temptations which surround policemen, and also that their
work is held up to exacting standards by business men and
insurance companies. The fact remains that our police forces are
constructed of the same human material as our fire fighting forces. It
is difficult to avoid the conclusion that if we adapt our requirements in
the regulation of vice to the capacities of our forces, (or vice versa); if
we criticise and appreciate their work in the same way as we do the
work of their sister department; if we place their appointment, tenure,
and promotion, upon grounds of merit and utterly exclude the
influence of the corrupt “higher-ups,” we will have gone a long ways
toward drying up the most despicable of the sources of political
corruption.

Certain of the moral aspects of tax dodging have been dealt with
in an earlier connection.[63] Contrary as it may seem to the principle
of economic interest there is a good deal of carelessness and
stupidity in this field, and cases are occasionally found of property
that has been over-assessed. On the other hand more or less
deliberate dodging is indulged in very largely. So far as this practice
deserves the stigma of corruption it is a stigma which rests to a very
considerable extent upon the so-called class of “good citizens.”
Certain residents of “swell suburbs” who daily thank God that their
government is not so corrupt as that of the neighbouring city are
among the worst offenders of this kind. As directors of corporations
men of the same standing are sometimes responsible for
monumental evasions. Of course what was said with regard to the
reaction of business against state regulation holds good here also.
There are plenty of legitimate methods of protesting against unjust or
oppressive taxes,—before the courts, before legislatures, and by
open propaganda designed to influence party organisations. But the
furtive concealment or misrepresentation of taxable values is a
matter of entirely different moral colour, and it is the latter practice
that we now have to consider.
Tax dodging is so common and so well established that it has built
up an exculpatory system of its own. Instead of bringing his
conscience up to the standards set by the law the ordinary property
owner inquires into the practice of his neighbours, and governs
himself accordingly. Wherever business competition is involved the
threat of possible bankruptcy practically forces him into this course.
Yet withal our citizen is likely to be somewhat troubled in his mind
about his conduct, at least until he learns how shamelessly John
Smith who lives just a little way down the street has behaved. This
information quite restores his equanimity, and at the next
assessment he may outdo Smith himself. Thus the extra legal, if not
frankly illegal, neighbourhood standard tends constantly to become
lower. And not only taxpayers but tax officials themselves are
affected by local feeling and fall into the habit of closing their eyes to
certain kinds of property and expecting only a certain percentage of
the valuation fixed by law to be returned.
Back of such neighbourhood ideas on taxation there are at least
two lines of defence. One is that our present tax system is highly
illogical, bothersome, and burdensome. To a considerable extent,
unfortunately, this is the case, but it does not justify illegal methods
of seeking redress. Not much argument is required to convince the
ordinary property owner that all the inequities of the existing system
fall with cumulative weight upon his devoted head. His pocketbook
affirms this view more strongly perhaps than he would care to admit,
but anyhow the net result is that he feels himself more or less
pardonable for evading the burden as far as he can. The other
common excuse for tax dodging is supplied by the conviction that
much of the money raised by government is wasted or stolen. The
logic based upon this premise is most curiously inverted, but none
the less it sways the action of great multitudes. Politicians are a set
of grafters, says our taxpayer. The more money they get the more
they will waste and steal. I will punish the rascals as they deserve by
dodging my taxes, that is by becoming a grafter myself. Seldom,
however, is the latter clause clearly expressed. Yet the existence of
corruption on one side of the state’s activities is thus made the
excuse for corruption on another side whereby the state is mulcted
of much revenue which it might receive. Of course evasion results in
higher tax rates, which, by the way, fall crushingly upon the citizen
who makes full and honest returns, and thus part of the loss in
income to the government is made up. It seems clear, however, that
in the long run government income is materially reduced by the
feeling prevalent among taxpayers which has just been described
and the procedure based upon it. On the whole this is by far the
most serious single economic consequence of political corruption. It
is bad enough that public money should be stolen, that public work
should be badly done, and that politicians and contractors should
grow rich in consequence, but it is far worse that the state should be
starved of the funds necessary to perform its existing functions
properly and to extend its activities into new fields. In the regulation
of industry, in education, philanthropy, sanitation, and art, American
government is very far from achieving what it should do in the public
interest and what it could do more efficiently and cheaply than any
other agency. Yet our progress toward this goal is perpetually
hindered by the existence of waste and corruption on the one hand,
and the consequent peremptory shutting of the taxpayers’
pocketbooks on the other hand.
Consideration of the theory underlying tax dodging reveals certain
broad lines of correction. In proportion as our tax system
approximates greater justice, the evasion which defends itself on the
ground of the inequities of the present system will tend to disappear.
To show how this may be done is beyond the limits of the present
study. Suffice it to say that the work which reformers and students of
public finance are now doing on inheritance, income, and corporation
taxes, on the taxation of unearned increment, on various applications
of the progressive principle, and so on, should eventuate in the
tapping of much needed new sources of income, and thus facilitate
the correction of present unjust burdens. The introduction of
economical methods and the elimination of the grosser forms of
corruption in the field of government expenditure will weaken the
excuses offered for evasion on the ground of public waste and graft.
There is an overwhelming mass of evidence to show that the
American taxpayer, once convinced of the necessity of a given public
work and further assured that it will be honestly executed, is
generous to the point of munificence. The annals of our cities are full
of the creation of appointive state boards composed of men of the
highest local standing and intrusted with the carrying out of some
great single project,—the erection of a city hall building, the
construction of a water works and filtration plant, or of a park system.
Very few such commissions are grudged the large sums of money
necessary for their undertakings. If every ordinary branch of our
government enjoyed public confidence to a similar degree such
special boards would no longer be needed, and ample funds would
be forthcoming from taxpayers for all our present functions and for
other new and worthy functions which might be undertaken greatly to
the public advantage. Finally our system of tax administration, like
our system of government regulation of business, needs
strengthening. Larger districts and centralised power in the hands of
the assessors will help to lift them above the neighbourhood feeling
which is responsible for so much evasion. Higher salaries will bring
expert talent and backbone sufficient to resist the pressure brought
to bear by large interests. As a matter of fact the first threat of a virile
execution of the laws wipes out a considerable part of the tax
dodging in a community.
There would also seem to be much virtue in the plan for the
reduction of the tax rate advocated by the Ohio State Board of
Commerce.[64] Given a community with a high general tax rate it
may be the case, for example, that only about fifty per cent of true
value is being returned. Everybody knows it; everybody is sneakingly
ashamed of it. Still fundamental honesty is supposed to exist in the
man who does not cut the percentage below say, forty; the really
mean taxpayer is he who risks twenty-five per cent on what he feels
obliged to return and conceals whatever he can into the bargain.
Under such circumstances it is proposed to take the heroic step of
reducing the tax rate to one-half its existing figure or even less.[65] If
this can be done it is hoped that taxpayers can be induced to return
their property at full value, and that much personal property will
come out of the concealment into which it has fled under the menace
of a high general property tax rate. In support of this argument cases
are cited where a reduction of the personal property tax rate alone
has brought in much larger returns and converted into a source of
revenue a form of taxation which everywhere under high rates shows
a tendency to dwindle to practically nothing.
As against the plan it may be said that taxpayers are habitually
suspicious and extremely likely to regard any change whatever as
certain to increase their burdens. Many of them would see nothing in
the proposition beyond a tricky device to screw up their valuations
under the pretext of low rates with the intention of falling upon them
later with rates as high or higher than before. Unless the reform were
fully understood and then backed up by the most vigorous
administration there would be grave danger that revenues would
materially suffer. Given these conditions essential to success,
however, the plan would seem decidedly worth trying. A community
willing to take the plunge, it is pointed out, would enjoy large
advantages over its less enterprising competitors in the advertising
value of a low tax rate, particularly as a means of inducing new
industries to locate in its midst. The reform would probably not
increase revenue, indeed it does not aim to do so, but it would yield
a moral return of immense value. Self respect would be restored to
many otherwise thoroughly good citizens, and public opinion, to the
tone of which the taxpaying class contributes largely, would be lifted
to higher planes. Under the present vicious system there must be a
considerable number who realise secretly and more or less vaguely
the inherent kinship between their conduct and that of the corrupt
political organisation under which they live, and who in consequence
remain inactive and ashamed when movements for better things in
city, state, or nation, are on foot.

In our earlier study of the nature of political corruption an effort

was made to distinguish between bribery and auto-corruption. As
examples of the latter, legislators may employ knowledge gathered
on the floor of the chamber or in committee rooms for the purpose of
speculating to their own advantage on stock or produce exchanges;
administrative officials who by virtue of their position learn in
advance any information which may affect the market (i.e., crop
reports) can do likewise; knowledge of important judicial decisions
before they are handed down may be exploited in a similar fashion;
insiders who have access to plans for projected public improvements
are in a position to acquire quietly the needed real estate for sale at
much advanced prices to the city or state when condemnation
proceedings are actually begun. In addition to large and striking
transactions of this sort there are innumerable smaller possibilities
for auto-corruption which present themselves to public functionaries
ranging in rank from the highest places in the official hierarchy to that
of the policeman on his beat. Logically the practices under
consideration are not separable from the general forms of political
corruption as the term is applied in the present discussion. Instead
they would seem to be a special method of carrying on corrupt
transactions of many different kinds. All cases of auto-corruption,
however, have the common feature that bribery by an outside
interest is excluded, and this absence of bribery has sometimes led
to the assertion that the practices included under this heading are
“honest grafts.” An illusory appearance of innocence is also
conferred by the difficulty of tracing the incidence of the burdens
resulting from such transactions. There is no moral ground for such
favourable distinctions, however. On the contrary, auto-corruption is
clearly worse than bribery in that an entire transaction of this
character must be guiltily designed and executed wholly by one
person, and that person an official charged with knowledge which
should be used only in the public interest. Moreover the profits of his
secret treachery may be turned entirely into his private bank
account. If so he cannot even plead in justification that he has been
acting in behalf of a party organisation by gathering and contributing
the funds necessary to its management. The latter feature of auto-
corruption stands in need of special consideration.
It may be laid down as a principle of fairly general applicability that
political corruption as such is disadvantageous to the party
organisation permitting it. From a purely tactical point of view it would
be the extreme of bad party management to tolerate loose conditions
under which a large number of officials could graft freely on their own
account and place the entire proceeds in their own pockets. Whether
they confined themselves to auto-corruption or accepted bribes
singly or in combinations the case would not be materially altered. A
day of reckoning at the polls would surely come, and it would find the
party treasury unprovided with the means of defence. Yet conditions
of this character prevailed pretty generally prior to the advent of
strongly centralised political machines. Corruption was extremely
diffuse, personal responsibility for it widely scattered, party
responsibility not so clear. Manipulation required whole corps of
lobbyists, “third houses,” “black horse cavalry,” and the like. Under
present conditions the party organisation with strongly centralised
management has a direct interest in limiting corruption and also in
seeing that contributions which arise from such practices as it
tolerates actually flow into the party war chest. Corruption in purely
selfish interest becomes treachery to the party as well as treachery
to the state. Of course even under strong centralised and permanent
party control cases of auto-corruption still occur, and at times officials
receive bribes without turning in their quotas. If so, however, it may
fairly be presumed that they make their peace with the organisation
in other ways. They may be exempt from paying tribute, but they are
nevertheless obliged to deliver votes or influence. Many sins are laid
at the door of the machine. It has at least the advantage of enabling
us to centralise responsibility for all corrupt practices which occur
under its management.
From this point of view one may undertake an outline of the form
of corruption connected with political control. All the preceding forms
of political corruption may be considered the obverse, this is the
reverse of the die. None of the practices earlier considered can be
carried on without danger; the corruption of political control is the
crooked means of avoiding the cumulative effects of these practices.
It is not popular, it is not good politics even in the narrowest practical
acceptance of that term, for a political organisation to grant corrupt
favours to business, to wink at the violation of the law by vice, to
allow its partisans in office to sell government property cheap and
buy government supplies dear. If any of these things are permitted
the organisation, like the common criminal, must take care to lay
aside “fall money” against a day of trial.
One might feel greater confidence in the restraining influence of
party centralisation were it not for the fact that the more dangerous
to party success are the forms of corruption which an organisation
tolerates the more lucrative they are apt to be. Though its sins be as
scarlet still they produce funds sufficient to buy indulgences and to
leave a handsome profit over. In connection with business
regulation, for example, bribery in any considerable amount is not
possible until legislation is enacted or close at hand. And legislation
of this kind is not likely to be passed or threatened unless a strong
public sentiment demands action. Political manipulation which
attempts to frustrate regulation at such a juncture must sooner or
later prepare itself to reckon with the public sentiment which it has
flouted. Vice cannot be tolerated except in contravention of laws
against it, and to do so means to offend the moral sentiment in the
community which placed such laws on the statute books. Franchise
grabbing is not profitable on a large scale until the experience of
earlier public service corporations has impressed upon the public
mind the great value of such grants. If, nevertheless, grabs are
permitted by the machine, the boodle must be sufficient to pay both
for the personal services involved and to repair any resulting
damage to party prestige at the next election. Of course many
citizens are apathetic with regard to such abuses or even ignorant of
their existence, and there are others who are so involved in corrupt
practices, particularly in connection with tax dodging, meter fixing,
and the protection of vice, that they feel themselves allied in interest
with the party organisation and accordingly vote its ticket. Always,
however, there is a contingent, and frequently it is large enough to
hold the balance of power, which is neither ignorant nor apathetic,
and which, although perhaps too quiescent ordinarily, will rise in
revolt against any organisation which grafts too boldly and too
widely.
The situation of the venal machine is, therefore, substantially this:
more money can be obtained at any time if certain practices
Welcome to our website – the ideal destination for book lovers and
knowledge seekers. With a mission to inspire endlessly, we offer a
vast collection of books, ranging from classic literary works to
specialized publications, self-development books, and children's
literature. Each book is a new journey of discovery, expanding
knowledge and enriching the soul of the reade

Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.

Let us accompany you on the journey of exploring knowledge and

personal growth!

ebooknice.com