Three Ways to Think About API Design

You don't need to see 5,000 APIs to know some are better than others. One of the reasons is the attention the API providers have paid to the designs of their APIs. Below are three people summarizing popular approaches and helping you think about API design, whether you're using someone else's or planning your own offering.

API Extensibility

Apperian encourages you to think about extensibility in the video embedded below:

Among the tips are to focus on the most scenarios and aim for self-documenting APIs.

Good APIs the Google Way

Google's Joshua Bloch has a great presentation (PDF). His general principles should not be skipped:

  • API Should Do One Thing and Do it Well
  • API Should Be As Small As Possible But
    No Smaller
  • Implementation Should Not Impact API
  • Minimize Accessibility of Everything
  • Names Matter–API is a Little Languag
  • Documentation Matters
  • Document Religiously
  • Consider Performance Consequences of
    API Design Decisions
  • Effects of API Design Decisions on
    Performance are Real and Permanent
  • API Must Coexist Peacefully with Platform

Via Maxime Gréau

API Ontology

A good overview of common approaches to APIs. Includes explanations of HTTP GET/POST, *-RPC, SOAP, "REST" (yes, in quotes) and Hypermedia.

I'm sure there are many other great examples of API design best practices. I hope you'll add your favorites in the comments.

Adam DuVander -- Adam heads developer relations at Orchestrate, a database-as-a-service company. He's spent many years analyzing APIs and developer tools. Previously he worked at SendGrid, edited ProgrammableWeb and wrote for Wired and Webmonkey. Adam is also the author of mapping API cookbook Map Scripting 101.



As one who consumes a lot of different APIs, I'll add to make it easy to explore. Maybe it was Twitter or Gowalla that first added the test consoles directly on their sites, but that's a great idea for producers of APIs. Short of that, as an API producer you better have a good reason for not letting me use tools like curl/ to explore your API. (had a frustrating experience lately with an API that required OAuth signing on all requests, even user less ones)

Great article, couldn't agree more! We at Apiary think that the current state of API documentation on the web is very sad. And we're building tools that help you deliver great API documentation with little effort and integrated into you development workflow. Drop me a line if you want to help us in our private beta.