Determining What Makes a Good API

From APIDesign

In this chapter, it becomes clear that you understand the term API to mean something much broader than most people do: in this book, an API is any kind of interface between software components (or even, I suppose, hardware components) including, say, a network protocol. This is potentially problematic because to most people an API is, well, an API, namely a set of functions or methods available in a library or class. So it's good that you're being so explicit about this. Although your use of this term is broad, I'm actually not sure if there's any better term than "API" to use throughout the book. You could say "interface", meaning a software interface, but that would probably be confusing because the book is Java-oriented and of course the term "interface" has another, more specific meaning in Java. So maybe it's just best to continue to use this term in the way you do, unless other reviewers have any better ideas about this.

--AdamDingle 00:09, 28 March 2008 (UTC)

I think the term API is fine. This is precisely the point Jarda's making, and it's a good one. If people think APIs are just method signatures, they are mistaken. After all, it stands for "Application Programmer Interface". All of Jarda's categories are examples of one developer creating an interface point for an application programmer, right? I think Jarda's goal is to get API developers to think more about how they expose functionality, and how to maintain those interfaces over time.

In fact, there are a few that I think he forgot:

• Database schemas are sometimes APIs. The last place I worked had a DB for storing logs, and that schema had to be evolved in a compatible way, as other teams were consuming the data in different ways and depended on the schema being stable.
• WSDL/REST/IDL: perhaps these are too obvious :-)
• XML Schemas: perhaps this is covered by the more general "files and their contents" section, but I think schemas deserve special mention. After all, we have large standards bodies that do very little beyond nailing down the semantics of XML schemas (e.g. w3.org)

• I used this list in bc11ce2d561c

--RichUnger Thu Mar 27 21:19:09 PDT 2008