4 ms·

How To Design A Good API and Why it Matters (2007) [video]

119 points by jdnc 10y ago

ciupicri 10y ago
Someone should add (2007) to the title.
- dang 10y ago
  Someone at your service. Kind of interesting that this was posted 15 times and never really discussed: https://hn.algolia.com/?query=How%20To%20Design%20A%20Good%20API%20and%20Why%20it%20Matters&sort=byDate&dateRange=all&type=story&storyText=false&prefix&page=0 https://hn.algolia.com/?query=How%20To%20Design%20A%20Good%2...
  - ttam 10y ago
    interesting, any idea why? how many times were the other threads opened? etc
  - s_dev 10y ago
    This regularly happens with most HN submissions. New can be equally as fruitful in its own right as front page.
clumsysmurf 10y ago
I think Android could have been much better if these principles were taken to heart during the design of the main APIs. From what I recall Josh collaborated with the Android team at some point; sadly too little too late. IMHO almost every Android API i use violates some principle in this presentation.
- pjmlp 10y ago
  So far I have spent more time on the NDK side than on the Java side, but for me the worst parts are the way Renderscript is bolted into the platform, all those m* member variables and anonymous classes everywhere.
- miguelrochefort 10y ago
  Android indeed has some of the worst APIs. They feel extremely inconsistent. iOS and Windows APIs are so much better. I think it's fair to assume that most people share the same experience.
- antiviral 10y ago
  My response (in good humor of course): https://cdn.meme.am/instances/500x/45999359.jpg https://cdn.meme.am/instances/500x/45999359.jpg More seriously, every sufficiently complex, real-life design I have ever seen has been a set of compromises to best meet a set of competing constraints. The most that I hope that a book or a lecture can do is provide a general set of principles that an engineer should consider, and be mindful of they are going to violate them. I can't think of any very complex platform that hasn't run into this issue, and Android is no different, and probably fares better than most. Do you have any examples that you would prefer instead?
  - chubot 10y ago
    Uh, isn't the obvious comparison iOS? I think the difference is that Apple had decades of institutional GUI expertise. Android engineers were more like hardware/OS guys as far as I can tell, and perhaps less experienced with the abstractions conducive to easily creating nice GUIs.
    - rqebmm 10y ago
      iOS and the Cocoa framework also have their fair share of hard to work with APIs. Like the OP said, you're always going to have to make compromises between conflicting requirements.
collyw 10y ago
This sounds just a lot my systems analysis and design classes years ago (waterfall days). Who would think of gathering requirements and specs in these days of Agile....
- Bombthecat 10y ago
  And Facebook showed clearly that you can change your API daily and no one cares.
  - guelo 10y ago
    Well, a lot of people care it's just that they don't have another option.
  - caseysoftware 10y ago
    Yes, when you become a de facto standard with 1.6B users, you get to set the rules. For everyone else, we have to provide good experiences with stable products.
  - gnaritas 10y ago
    Everyone cared and complained loudly, so no, they really didn't.
jolux 10y ago
And people say there's nothing copyrightable in an API design...
- magicalist 10y ago
  Just because something is a creative act doesn't mean it's covered by copyright. If your functional creation is useful and novel, get a patent on it.
  - jolux 10y ago
    I'd argue that the functional part of all APIs is nearly identical and that the creative part is what differentiates them.
    - magicalist 10y ago
      > I'd argue that the functional part of all APIs is nearly identical and that the creative part is what differentiates them. You misunderstand. It's not that functional things are covered by patents, "creative" things are covered by copyright. First, functional things can of course be creative; that's in the very definition of invention. Second, copyright is limited by law to the expression of an idea, not the idea itself. US law is very clear about this: > In no case does copyright protection for an original work of authorship extend to any idea, procedure, process, system, method of operation, concept, principle, or discovery, regardless of the form in which it is described, explained, illustrated, or embodied in such work. Source code is indisputably copyrightable, but the question of law is if the functional aspect of an API, the way you interoperate with it, is protected by copyright. I believe Judge Alsup decided correctly that an API is a "system or method of operation", avoiding "the danger of conferring a monopoly by copyright over what Congress expressly warned should be conferred only by patent". I'm hopeful that the other circuit courts will agree.
      - jolux 10y ago
        And when you copy source code that has an API in it, you violate the copyright for that source code. This is not hard.

119 points by jdnc 10y ago

ciupicri 10y ago

Someone should add (2007) to the title.

dang 10y ago
Someone at your service. Kind of interesting that this was posted 15 times and never really discussed: https://hn.algolia.com/?query=How%20To%20Design%20A%20Good%20API%20and%20Why%20it%20Matters&sort=byDate&dateRange=all&type=story&storyText=false&prefix&page=0 https://hn.algolia.com/?query=How%20To%20Design%20A%20Good%2...
- ttam 10y ago
  interesting, any idea why? how many times were the other threads opened? etc
- s_dev 10y ago
  This regularly happens with most HN submissions. New can be equally as fruitful in its own right as front page.

clumsysmurf 10y ago

I think Android could have been much better if these principles were taken to heart during the design of the main APIs. From what I recall Josh collaborated with the Android team at some point; sadly too little too late. IMHO almost every Android API i use violates some principle in this presentation.

pjmlp 10y ago
So far I have spent more time on the NDK side than on the Java side, but for me the worst parts are the way Renderscript is bolted into the platform, all those m* member variables and anonymous classes everywhere.
miguelrochefort 10y ago
Android indeed has some of the worst APIs. They feel extremely inconsistent. iOS and Windows APIs are so much better. I think it's fair to assume that most people share the same experience.
antiviral 10y ago
My response (in good humor of course): https://cdn.meme.am/instances/500x/45999359.jpg https://cdn.meme.am/instances/500x/45999359.jpg More seriously, every sufficiently complex, real-life design I have ever seen has been a set of compromises to best meet a set of competing constraints. The most that I hope that a book or a lecture can do is provide a general set of principles that an engineer should consider, and be mindful of they are going to violate them. I can't think of any very complex platform that hasn't run into this issue, and Android is no different, and probably fares better than most. Do you have any examples that you would prefer instead?
- chubot 10y ago
  Uh, isn't the obvious comparison iOS? I think the difference is that Apple had decades of institutional GUI expertise. Android engineers were more like hardware/OS guys as far as I can tell, and perhaps less experienced with the abstractions conducive to easily creating nice GUIs.
  - rqebmm 10y ago
    iOS and the Cocoa framework also have their fair share of hard to work with APIs. Like the OP said, you're always going to have to make compromises between conflicting requirements.

collyw 10y ago

This sounds just a lot my systems analysis and design classes years ago (waterfall days). Who would think of gathering requirements and specs in these days of Agile....

Bombthecat 10y ago
And Facebook showed clearly that you can change your API daily and no one cares.
- guelo 10y ago
  Well, a lot of people care it's just that they don't have another option.
- caseysoftware 10y ago
  Yes, when you become a de facto standard with 1.6B users, you get to set the rules. For everyone else, we have to provide good experiences with stable products.
- gnaritas 10y ago
  Everyone cared and complained loudly, so no, they really didn't.

jolux 10y ago

And people say there's nothing copyrightable in an API design...

magicalist 10y ago
Just because something is a creative act doesn't mean it's covered by copyright. If your functional creation is useful and novel, get a patent on it.
- jolux 10y ago
  I'd argue that the functional part of all APIs is nearly identical and that the creative part is what differentiates them.
  - magicalist 10y ago
    > I'd argue that the functional part of all APIs is nearly identical and that the creative part is what differentiates them. You misunderstand. It's not that functional things are covered by patents, "creative" things are covered by copyright. First, functional things can of course be creative; that's in the very definition of invention. Second, copyright is limited by law to the expression of an idea, not the idea itself. US law is very clear about this: > In no case does copyright protection for an original work of authorship extend to any idea, procedure, process, system, method of operation, concept, principle, or discovery, regardless of the form in which it is described, explained, illustrated, or embodied in such work. Source code is indisputably copyrightable, but the question of law is if the functional aspect of an API, the way you interoperate with it, is protected by copyright. I believe Judge Alsup decided correctly that an API is a "system or method of operation", avoiding "the danger of conferring a monopoly by copyright over what Congress expressly warned should be conferred only by patent". I'm hopeful that the other circuit courts will agree.
    - jolux 10y ago
      And when you copy source code that has an API in it, you violate the copyright for that source code. This is not hard.