Three Ways to Think About API Design

Adam DuVander, February 14th, 2012

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.

Both comments and pings are currently closed.

4 Responses to “Three Ways to Think About API Design”

February 15th, 2012
at 7:08 am
Comment by: Jakub Nesetril

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.

February 15th, 2012
at 10:03 am
Comment by: Ryan Williams

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/hurl.it to explore your API. (had a frustrating experience lately with an API that required OAuth signing on all requests, even user less ones)

February 22nd, 2012
at 3:32 pm
Comment by: Today in APIs: Facebook Authorization, API Design and 38 New APIs

[...] What would you add to that list? Last week we covered three ways to think about API design. [...]

February 24th, 2012
at 3:10 am
Comment by: Today in APIs: Facebook Authorization, API Design and 38 New APIs | My Blog

[...] What would we supplement to that list? Last week we lonesome three ways to consider about API design. [...]

Follow the PW team on Twitter

ProgrammableWeb
APIs, mashups and code. Because the world's your programmable oyster.

John Musser
Founder, ProgrammableWeb

Adam DuVander
Executive Editor, ProgrammableWeb. Author, Map Scripting 101. Lover, APIs.