Good API Design Principles: Building Lasting Interfaces
Technology Corrected & verified

Good API Design Principles: Building Lasting Interfaces

Published by When Notes Fly · View original ↗

Explore effective API design strategies, focusing on resource-oriented URLs and proper application of HTTP methods.

What is this page about?

A guide to good API design principles, the conventions that determine whether an API stays intuitive, stable, and evolvable as developers adopt it. It covers resource-oriented design and the noun-verb distinction, HTTP methods as a semantic vocabulary, hierarchical URL design, consistency in naming and response structure, error handling with correct status codes and actionable messages, versioning and what counts as a breaking change, authentication and authorization, pagination and filtering, and documentation via the OpenAPI specification.

What has been corrected on this page?

Every accepted correction to this page is recorded with the exact change, so readers can see how the page improved over time.

  1. 11 July 2026 · corrected by Melik Can Sariyer

    2 corrections applied: Twitterrific launched 2007, TweetDeck and HootSuite in 2008 - not 'within months' of the 2006 API; the ecosystem developed over a few years | The $817 billion figure was Stripe's 2022 total payment volume (reported early 2023); 2023 was roughly $1 trillion

    Before

    Within months, an entire ecosystem of applications emerged over the next few years: Twitterrific, TweetDeck, HootSuite...

    After

    Over the next few years, an entire ecosystem of applications emerged: Twitterrific, TweetDeck, HootSuite...

    Why: The Stripe $817B/2022 fix was already correctly applied, but a residual self-contradictory phrase survived a prior partial edit: 'Within months, ...emerged over the next few years' mixed the original unverified rapid-timeline claim with the corrected multi-year framing. Removed 'Within months,' so the sentence consistently reflects gradual ecosystem growth.

    View the full record →

Who checked this page?

1 contributor has checked "Good API Design Principles: Building Lasting Interfaces" on When Notes Fly. Each name below links to that person's public CitePep profile, where every contribution they have made is listed with the exact change they proposed.

Melik Can SariyerExpert Contributor