Talk: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

This might be a good place to mention the less obvious drawbacks of using reflection as an intentional part of an API.

1. It is too easy to bypass normal Java access control.
2. IDE tools such as Find Usages will not work well.
3. Very basic refactorings such as Rename can transform a correct program into a broken program.
4. Many basic design patterns, such as proxies, are rendered impossible.
5. It is not possible to vary part of a program dynamically if it is controlled by reflective information rather than a normal method call.

I think a lot of people get seduced by the apparent ease of coding made possible by some reflection tricks and do not grasp what invariants on program behavior they are discarding. This loss of flexibility can also have destructive effects on the ability of an API to be evolved smoothly; the client code becomes passive text and so cannot try to use features of a new API if and when they are determined to be available at runtime.

Gratuitous usage of annotations can also result in the exact same problems. By "gratuitous" I mean tricks based on access to annotation information which could just as easily have been designed as regular Java interfaces. For example, javax.annotation.processing.SupportedSourceVersion is entirely gratuitous since AbstractProcessor.getSupportedSourceVersion() could simply have been left as an abstract method with no ill effect on the readability of an subclass. Legitimate uses of annotations include:

1. marking some aspect of a body of code of interest to static source analysis
2. declarative registration of some objects without requiring class loading
3. declaring a method or class to need to be processed by a container in some special aspect (e.g. transactionally), where forcing such behavior by programmatic means in the code itself would either be unwieldy or impossible

--JesseGlick 23:14, 26 March 2008 (UTC)

Most of the caveats I mentioned in relation to reflection in the previous section could be applied equally to file-based configuration.

--JesseGlick 23:27, 26 March 2008 (UTC)

• pg 26, last para: "Just like a giant" => "Just as the giant"
• pg 27, para 1: "one filesystem" => "one virtual filesystem"
• pg 27, para 1: "how unionfs work" => "how unionfs works"
• pg 27, para 1: "big, merged" => "merged"
• pg 27, para 1: "individual components layers" => "individual component layers"
• pg 27, figure caption: "FileSystem" => "filesystem"
• pg 27, para 2: "I made it back 2000" => "I made it back in 2000"
• pg 27, last para: "are obvious" => "is obvious"
• pg 27, last para: "kerberos", last occurrence: should be in red or capitalized

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

• The picture of the sandwich was amusing, but did not really explain the concept of the XML filesystem.
• I think the discussion of how the XML-based filesystem works is interesting but not necessarily relevant to API design.

--TomWheeler Thu Mar 27 21:23:09 CDT 2008

• Figure 4-1 is falling off the edge of the page
• "unionfs" means union file system
• Page 27: "layers:" should end with a period, not a colon.
• I'm not sure how the caption of Figure 4.2 applies to the picture, or how the picture applies to the section

--Dmkoelle 21:48, 4 April 2008 (UTC)

The CWD for a process is not determined by the PWD environment variable. It is the other way around. In fact few Unix utility programs pay much attention to env vars (POSIXLY_CORRECT excepted). At least in my experiment, changing PWD has no effect on where a text file is saved, as claimed.

• Thanks a lot. I've change the example to something that shall work dfc07704f66a

--JesseGlick 23:35, 26 March 2008 (UTC)

• "Java used to have another similar replacement": Java still has system properties, yes? So you can't say "used to have"; you could say something like "has always had" or "has long had".
• section title: "Command Line" => "Command-Line"
• p 28, last para: "advertize" => "advertise"
• p 28, last para: "using NetBeans IDE" => "using the NetBeans IDE"
• p 28, last para: "NetBeans Platform, it is mainly": comma should be a semicolon (run-on sentence)
• p 28, last para: "ensure this API" => "ensure that this API"
• p 29, para 1: "may completely break the application" => "may completely break an application"
• p 29, para 1: "any documented variable" => "any documented variables"

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

I guess you meant that people should be using FileUtil.toFile, not FileObject.getPath, in lieu of FileObject.toString. getPath is in fact another example of a method returning a string which looks like it could be used for constructing a File path, yet really cannot. So the drama thickens.

--JesseGlick 23:52, 26 March 2008 (UTC)

• p 29, para 2: "predecesors" => "predecessors"
• p 29, para 2: "also many followers" => "also its many followers"

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

• "followers, then" - remove "then"
• In "Misuse of toString", use toString() in the title.
• In "Misuse of toString", the parenthetical URL seems misplaced.

--Dmkoelle 21:49, 4 April 2008 (UTC)

• p 30, para 4: "Quite similar, yet slightly different to textual and file based APIs are protocols": this word order seems slightly unnatural. I might somewhat prefer "Protocols are quite similar to textual and file-based APIs, yet slightly different".
• p 30, para 4: "Especially formats of...": I might reword this as "The formats of messages sent over a network are of especially great importance."
• p 30, para 5: "package private": this should be in red like the preceding keywords.
• p 30, para 5: "is access wide" => "confers unlimited access"
• p 30, para 6: "Subversion, the version control system," => "the version control system Subversion" (fine as is, but this would read slightly more smoothly)
• p 30, para 6: ", and the challenges they faced" => ", the challenges its developers faced"
• p 31, para 1: "the local check out" => "a local checkout"
• p 31, para 1: "the most important part, once Subversion" => "the most important part: once Subversion" (run-on sentence)
• p 32, para 3: "Since then I know" => "Since then I have known"
• p 32, para 3: "handshake. Even if the" => "handshake -- even if the" (fix sentence fragment)
• p 32, para 5: "inside single svn binary" => "inside the single svn binary"
• p 32, para 5: "for common usages" => "for common usage"
• p 32, para 6: "exposed to the clients" => "exposed to clients"
• p 32, para 6: "usage simplicity" => "simplicity"

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

• Page 30: It's odd to say "you immediately enter an API business." I think it would be more natural to say "you immediately enter the API design business."
• Page 30: It's odd to say "but opening a socket is access wide." It would be more natural to say "but there is no restriction on who can open a socket." Although this is not technically accurate, since only the root user can open ports < 1024 on UNIX systems.

--TomWheeler Thu Mar 27 21:58:13 CDT 2008

What is "Basic English"?

• See Wikipedia

In fact, IIRC, Subversion follows a common pattern for protocol compatibility whereby a client or server is only guaranteed to be able to communicate with a server or client (resp.) of the same major version or an immediately preceding or succeeding major version. For example, your 1.4 client can communicate with 1.3, 1.4, or 1.5 servers. It might send unrecognizable stuff to a 1.2 server, and might get unrecognizable responses from a 1.6 server. This policy preserves the ability of people to upgrade their clients and servers pretty freely, so long as they do not fall badly out of date, while offering Subversion developers an opportunity to make significant changes to the protocol over time, including cleanup of long-obsolete features and mistakes. I know the DocBook project follows a similar policy, in that case for a file format rather than a protocol: for example, a tag can be deprecated in DocBook 4.7 but cannot be deleted until 4.8, giving authors time to update any usages of that tag while permitting them to preview 4.7 if their documents were known to be "clean" in 4.6.

--JesseGlick 23:07, 1 April 2008 (UTC)

• "Especially formats of..." is passive voice. Rephrase.
• "access wide" is not a term I'm familiar with.
• Page 31, para 1: "And last but not least," can be deleted
• Page 31, para 1: semicolon instead of comma in "part, once Subversion"

--Dmkoelle 21:51, 4 April 2008 (UTC)

• p 32, para -2 (i.e. second to last): "the blackbox building blocks": delete "the"
• p 32, para -2: "it usually isn't,": replace comma with colon
• p 33, para 2: "non null" => "non-null"

--AdamDingle 01:01, 28 March 2008 (UTC)

• "However usually it isn't, regardless" -> "However, usually it isn't. Regardless"
• Good stuff in this section.

--Dmkoelle 21:52, 4 April 2008 (UTC)

• The title should include the full words "internationalization" and "localization"; the terms I18N and L10N are very informal and are appropriate for a whiteboard discussion, but not a book heading
• p 33, para 4: "APIs between the Linux kernel" => "APIs between Linux kernel components"
• p 33, para 4: "low level" => "low-level"
• p 33, para 4: "behind my own programming horizon" => "beyond my own programming horizon"
• p 33, para 5: "hard coding" => "hard-coding"
• p 33, para 5: "during the program execution" => "during program execution"
• p 33, last para: "behind the horizon" => "beyond the horizon"
• p 34, para 1: "work well" => "works well"
• p 34, para 2: "UI" => "user interface" (the term "UI" is too informal to use here)
• p 34, para 2: "I read an HTML," => "I read an HTML document,"
• p 34, para 2: "to make this works" => "to make this work"
• p 34, para 2: "on my Linux" => "on my Linux machine"
• p 34, para 3: "we receive most of the bug reports from this combination": this sounds somewhat awkward. I'd suggest rewording the entire sentence like this: "We receive many bug reports from localizers who often use Solaris and translate mostly to Japanese."
• p 34, para 3: "so much fun" => "so fun"
• p 34, para 3: "problems with this combination" => "problems with this environment"
• p 34, para 4: "we know that most complicated" => "we know that the most complicated"

--AdamDingle 01:07, 28 March 2008 (UTC)