[autarch]

All that these sorts of description produce is a low-level API. That can be useful, but what's really needed are high-level APIs that provide meaningful semnatics:

    my $me = Facebook->new( username => 'autarch' );
    $me->post_status("I'm on Hacker News writing this comment");

    my $friend = Facebook->new( username => 'imaginary' );
    $me->post_on_wall( $friend, "Hey buddy, I am on Hacker News writing this comment" );

[ahallock]

Exactly. And this is what clients can provide over generic, one-size-fits-all solutions: fluent, idiomatic, and terse access to APIs.

[autarch]

Here's another way to phrase it. A good API is based on the data and actions related to a specific domain of knowledge. Generic solutions produce APIs that are oriented around the communications protocol (REST).

On the client side, I don't really care (too much) if something is a POST or PUT, I want to send a message or update a repository's metadata or share a photo.