I've never made a public API before. Feedback on this one? | Hacker News Reader

I've never made a public API before. Feedback on this one?

helpbubble.com

30 pointsdustball14 comments

Don't do this:

  var oldonload = window.onload;

Try to avoid touching the global namespace. At most register one object in it: HelpBubble. Use callbacks for the init, open, close, and clicked events. Look at how jQuery does it.

These are too long:

  HelpBubble.API.setText()
  HelpBubble.API.setMenuStyle()
  HelpBubble.API.setButtonStyle()

I would use:

  HelpBubble.API.text()
  HelpBubble.API.menuStyle()
  HelpBubble.API.setButtonStyle()

Passing it nothing should return the current value (for the latter two it should return objects). Setting it should take either objects or strings.

Also, do you expect to only have one instance of these at a time? If not, your API might not work very well.

JQuery does the same.

$("#element").html($("#element").html() + custom_html);

Yes, and I very much like that API. It's concise which is a huge win when you have to read that code later.

Can't you just type $("#element").append(custom_html)?

I can't give you feedback on your specific API. However, I will say that if you're not already about 80% sure that it's correct, it's probably wrong somehow.

Allow me to explain. An API is a pretty abstract thing. For it to be useful, you need to have a use-case for it. Generally, once you've defined what the problem is that you're solving, you know about 80% of what the API needs to look like. The rest is just a matter of iteration and trial and error.

The best way to get at this is to write an application that uses the API. This should give you a pretty good idea of what kind of interface should be provided. Alternatively, your customers should give you an idea of what they want the API to do. Don't be afraid to ask probing questions if their needs are ambiguous.

And if you're 100% sure it's correct, it's probably wrong somehow.

Not the API, but I went to the homepage and tried out the help bubble. The text went outside the bubble, which made it hard to read and didn't look very nice. This is Firefox 3.6.3 on Windows XP. I also have a custom DPI, but that usually just causes problems in IE.

same happened for me on xp, firefox 3.0.19

same on Chrome/Vista

IE 8.0.7600.16385 on Windows 7 x64 has the text going outside the buggle on the right, as well the background color of the header extending out to the right as well.

Chrome 5.0.375.70 on "" also has the text flowing past the right side, but the header bg doesn't.

I suspect the issue is you UL is 100% width, plus padding, but I'm no CSS whiz.

Cool idea though and good question, I've been curious about how to make a public API as well.

Remove the ".API".

Id be interested in putting a bubble on my site, but did not see a Demo. I saw Try it which took me to another page asking me to enter a title, which I did and then I hit ok and it took me to another page but did not preview my test bubble. Is there a Demo for users to try beforehand?

This is related more to the HelpBubble itself, but it would be great if the bubble can be moved around the page via drag-and-drop.

Neat idea! I noticed some display issues in IE 8.

Reply on news.ycombinator.com