How to Design a Good API and Why it Matters

Nov 2, 2026

Uploaded by Margaret

API design is presented as a strategic lever that can create lasting value or cause ongoing maintenance costs. The material explains why public APIs must be correct early, and how thinking in APIs improves modularity, reuse, and code quality. It outlines core characteristics of a good API, then guides requirements gathering, starting with short specifications, writing API-facing code early, and extending the same discipline to SPI plug-in interfaces.

LanguageEnglish

CategoryTechnology

FormatPDF

Pages49

Reading Time2 h 3 min

AccessFree to download

Why is API Design Important?

Why is API Design Important to You?

Characteristics of a Good API

Outline

The Process of API Design

General Principles

How to Design a Good API and Why it Matters Joshua Bloch Principal Software Engineer 1 How to Design a Good API and Why it Matters Why is API Design Important? • APIs can be among a company's greatest assets Customers invest heavily: buying, writing, learning Cost to stop using an API can be prohibitive Successful public APIs capture customers • Can also be among company's greatest liabilities Bad APIs result in unending stream of support calls • Public APIs are forever-one chance to get it right 2 How to Design a Good API and Why it Matters Why is API Design Important to You? • If you program, you are an API designer Good code is modular–each module has an API • Useful modules tend to get reused Once module has users, can’t change API at will Good reusable modules are corporate assets • Thinking in terms of APIs improves code quality 3 How to Design a Good API and Why it Matters Characteristics of a Good API • Easy to learn • Easy to use, even without documentation • Hard to misuse • Easy to read and maintain code that uses it • Sufficiently powerful to satisfy requirements • Easy to extend • Appropriate to audience 4 How to Design a Good API and Why it Matters Outline I. The Process of API Design II. General Principles III. Class Design IV. Method Design V. Exception Design VI. Refactoring API Designs 5 How to Design a Good API and Why it Matters I. The Process of API Design 6 How to Design a Good API and Why it Matters Gather Requirements–with a Healthy Degree of Skepticism • Often you'll get proposed solutions instead Better solutions may exist • Your job is to extract true requirements Should take the form of use-cases • Can be easier and more rewarding to build something more general Good 7 How to Design a Good API and Why it Matters Start with Short Spec–1 Page is Ideal • At this stage, agility trumps completeness • Bounce spec off as many people as possible Listen to their input and take it seriously • If you keep the spec short, it’s easy to modify • Flesh it out as you gain confidence This necessarily involves coding 8 How to Design a Good API and Why it Matters Write to Your API Early and Often • Start before you've implemented the API Saves you doing implementation you'll throw away • Start before you've even specified it properly Saves you from writing specs you'll throw away • Continue writing to API as you flesh it out Prevents nasty surprises Code lives on as examples, unit tests 9 How to Design a Good API and Why it Matters Writing to SPI is Even More Important • Service Provider Interface (SPI) Plug-in interface enabling multiple implementations Example: Java Cryptography Extension (JCE) • Write multiple plug-ins before release If you write one, it probably won't support another If you write two, it will support more with difficulty If you write three, it will work fine • Will Tracz calls this “The Rule of Threes”(Confessions of a Used Program Salesman , Addison-Wesley, 1995) Bad 10 How to Design a Good API and Why it Matters

FAQs

Why is API design important for a company?

APIs can become major assets that customers invest in, learn, and reuse. Conversely, bad public APIs create a constant stream of support and are hard to fix later.

What characteristics define a good API?

A good API is easy to learn and use, hard to misuse, and supports clear reading and maintenance. It is sufficiently powerful, easy to extend, and appropriate for its intended audience.

How should requirements and specifications be handled in API design?

Extract true requirements in the form of use-cases, and be skeptical of proposed solutions. Start with a short specification (about one page), bounce it off stakeholders, then flesh it out as confidence grows through coding.

Nov 2, 2026

Uploaded by Margaret