Revisiting API design from another perspective

[mystran]

I am well aware that many will find several (if not all) of these important.

Also, please try to answer as "application programmers" not "API designers", as I am more interested in what kind of API people want to use, than what they consider as good design. (Personally I found a difference here..)

[Dreamsmith]

Tough choice! They're all nice features. As for what comes first, I was having trouble deciding between simple and lightweight, but finally decided upon simplicity, as lightweight more appeals to be as a designer than as an application developer. Also, I weaseled a bit, deciding in my mind that simplicity implied lightweight, but not necessarily the other way around, so you get a two-for-one deal placing simplicity on top.

I know, I know, simple interface doesn't imply simple implementation (quite the opposite, frequently). But then that doesn't really count as simplicity in my book, that's just complexity hidden. When I say simplicity, I mean more than a simple facade.

Anything that tries to do everything is guarenteed to be a bloated, bug-ridden mess. "Completeness" is only a virtue if you've got a small, well defined problem area. Enlarge the domain and it becomes the worst idea on the list.

And the best form of "modularity" is a multiplicity of completely stand-alone API's or libraries. Integration comes naturally if they're all small, well-defined, and unambitious. You only have problems with seperate API's and wish they were integrated when they start stepping on each other's toes, and they only do that when they were insufficiently focused to begin with. The problem then isn't that they aren't integrated, the problem is they're too big to begin with.

[mystran]

Tough choice! They're all nice features. As for what comes first, I was having trouble deciding between simple and lightweight, but finally decided upon simplicity, as lightweight more appeals to be as a designer than as an application developer. Also, I weaseled a bit, deciding in my mind that simplicity implied lightweight, but not necessarily the other way around, so you get a two-for-one deal placing simplicity on top.

This is the classic "new jersey" vs "mit" style of simplicity, the "lightweight" here trying to put emphasis on the "new jersey" style "implementation simplicity" but I wanted separate terms. It seems you got the idea though

And the best form of "modularity" is a multiplicity of completely stand-alone API's or libraries. Integration comes naturally if they're all small, well-defined, and unambitious. You only have problems with seperate API's and wish they were integrated when they start stepping on each other's toes, and they only do that when they were insufficiently focused to begin with. The problem then isn't that they aren't integrated, the problem is they're too big to begin with.

I agree to a point. You can have separate APIs in the sense that they are totally separate libraries, with no dependencies to each other, which ofcourse is the highest possible point in "modularity", but one might still want them to be part of one large "API base" so that the basic principles are the same from one API to another.

I wasn't trying to imply "an API" to be one gigantic heap of code, but rather any set of libraries or system interfaces provided, so in a sense, this "separate parts" was exactly what I had in mind when writing the option. Should have been more clear I think..

[Candy]

I voted for lightweight, but that's because it was mostly what I thought would be the best feature. The exact feature would be that each function has explicitly one well-defined function, and most certainly not multiple.

This is their order of importance for me:

Lightweightness(?): one API function should only do one, simple thing
Simplicity: most common things should be as simple to do as possible
Transparency: the API can be extended and even partially bypassed without writing extensive amounts of glue code
Consistency: the API as a whole follows the same few principles
Completeness: covers most of what anyone would want to do
Modularity: one can use certain parts of an API without fully commiting to the API model as a whole

Examples:
Lightweightness: good, close(int fd). It closes a file descriptor, no questions asked. Bad: Open(int fd, int mode[, int flags]). It either opens a file, truncates a file, opens it for append, creates an entirely new file... and if you don't specify the optional flags you end up with a setgid nobody-read-or-writable file. Other examples include ioctl and fcntl.
Simplicity: There should be no complex functions. See lightweightness for description, the same two are good and bad. Although I'd pick fcntl this time
Transparency: You should be able to hide the entire API very quickly behind your own facade, making it very accessible for people that don't like it, or that like complex functions or anything. It also should allow easy (well... relatively) access from OO languages, since there are numerous people using them. Good design would be for instance fork(), since it doesn't hold anything non-portable to OO design. Bad design in this case is pthread_create, in that you have to create a static function for each call you'd like to make, with a struct to go with it.
Consistency: Each function uses the same execution idea, and not a completely different one. Good would be the unix stuff, where socket() returns an fd, open() returns one, and you can open devices of all types also returning an fd. In Windows you get a few different types, and you have to use different functions with equivalent names for the access, not making it any clearer (read or recv or ..., send or write or ...) for people first learning it.
Completeness: I don't like having features inaccessible, but in most cases no OS designer leaves out essential features. The nonessential ones are built up from the essential ones, so that allows you to make them yourself, in effect, making them complete again. This thus doesn't weigh high for me.
Modularity: I am kind of missing the point of this one. Why would you want to be able not to use an API, or parts of it, if there's no other API in the OS? Do you imply mix&match fishing-up your own API? That's a bad thing. You'll make code that others can't read, and you can't read others code. Use one API for the language, and make it clear. If others want a different one, kind of, tough.

In short, I like functions that are simple to use, do one thing, preferably do them well (pretty DUH) and have no unintended side-effects (say, a close that randomly picks a fd, open that doesn't give anybody access).

[Solar]

I voted consistency.

Whether it can be lightweight or not depends on the feature set. A dedicated file server OS can make do with a couple dozen API calls. A full-fledged multimedia desktop OS cannot provide anything "lightweight" due to the sheer volume of functionalities.

Completeness is a Must Have (tm); any API that isn't complete is simply unfinished, and we are talking v1.0 API's here, no?

Transparency and Modularity, as you defined it, is A Bad Thing (tm) in my book. Don't weasel around the API, you'll get bitten in v2.0. There are other definitions of Transparency and Modularity that would get high marks from me (like, one API for filesystem access, with the actual file system being a modular backside plug-in). But that's what API's are all about, so that's the same category as "Completeness" for me.

Leaves Simplicity and Consistency. That's a hard choice. Then again, if every individual API call of yours is as simple as can be, but every one follows a subtly different concept, that's not as "simple" as following one single paradigm, be it complex as long as it's consistent (and thus, easy to remember once you got the idea).

[Legend]

I think if your API is modular, you can get completeness over time.

However, they should be consistent, which helps simplicity. There is no collection of APIs that is simple if it is not consistent.

[Pype.Clicker]

Voted for "consistency" aswell ... Reading Perl documentations more and more makes me realize that, when achieved, the "rule of minimizing surprise" is a golden rule.

I mean, the dev'er should be able to understand quickly the concepts of your API, and your API should obey as little 'rules' as you can see ... If you have lot of 'exception' rules (like in french grammar?), the API begins to get tedious to use and error prone. The best counter example i can imagine is the Java stl where you have 3 or 4 way to access an element within a collection of items and you can never tell which way you should use in a specific case ...

[mystran]

Actually, I just stubled across something I've known for a lot of time, but didn't know it had a name, which is "REST".. (and especially well known in Python community I hear)

And if I got it right, the point in the probably most well-known case is that HTTP is a full messaging protocol: messaging protocols on top of HTTP are just bloat, and might even be harmful.

The argument goes that you already have GET, which get's stuff, and POST which affects stuff. In both cases the URI is sufficient to indicate what you want to do.

The argument goes somewhat like: providing especially a GET handler for a specific URI is almost trivial. If you need to dump same data in several XML formats, that's not that bad, since you just implement a new URI for each new format. No backwards compability issues, what so ever.

Even in POST case you can implement new version as new URI's, which just do something more than the old version. Again, no need to break any existing code in most cases.

something like that anyway..

[Legend]

XML over HTTP? You are on the way of reinventing SOAP then
And when you are already there, you are on your way to web services!

[Solar]

Ahem... HTML is XML...

[Legend]

Given the right DTD

[mystran]

XML over HTTP? You are on the way of reinventing SOAP then
And when you are already there, you are on your way to web services!

Ah, but the point of REST is that SOAP is totally unnecessary bloat, because HTTP is already a suitable messaging protocol for XML as it stands =)

[Legend]

I can perhaps use several different URIs for each function one, however, I still need a standard way of encoding parameters.

[Dreamsmith]

Ah, but the point of REST is that SOAP is totally unnecessary bloat, because HTTP is already a suitable messaging protocol for XML as it stands =)

How odd. If you were the kind of person would actually dislikes unnecessary bloat, you wouldn't be using XML to begin with, not with so many simpler and better alternatives available (c.f. http://www.pault.com/pault/pxml/xmlalternatives.html), so actually being concerned about extra bloat seems out of character here. If you like XML, you ought to love SOAP...

[mystran]

Ah, but I wasn't advocating XML. I was just trying to get the point that these REST people have (which btw is that you can add the desired format part of the URL too, so you have have your result in whatever format you want. And no, this is not hard to support.)

Besides, while I'd be perfectly happy to have everything as S-expressions (or pretty much anything else just as well), many people seem to think that XML looks less frightening (which ofcourse is totally irrelevant when you exchange data between two programs, but such is life).