News for hackers. Stuff that matters.
Re:Annoyances of API Design by gaara87 on Thursday January 28, 2016 @02:41PM (#10990645)
So... what is an example of a well written API/SDK?
Re:Annoyances of API Design by JadeNB on Thursday January 28, 2016 @03:31PM (#10991051)
> So... what is an example of a well written API/SDK?

I think that this is an underrated question. I am not a programmer, but a mathematician; I will write from my experience in that field.

I was trying to understand a paper which used horrible, ad hoc notation that obscured the simple ideas at its centre. I invented a new, harmonious notation that beautifully revealed these simple ideas, and wrote a paper using it.

The notation was beatiful and harmonious as long as you were its inventor, and it was the most recent thing that you had been thinking about. Now, when I go back and read that paper … I think "wow, this horrible notation obscures the simple ideas at the centre of the paper."

Incidentally, I still think that the notation is better than the original; but the main thing that I've learned is to do it yourself before you complain about what someone else has done—after which (a) you'll have a good implementation and won't need to complain, or (b) you'll feel much humbler and won't want to complain.

Re:Annoyances of API Design by allengeorge on Thursday January 28, 2016 @11:01PM (#10993403)
Or maybe, the takeaway is: revisit your work later, when it's no longer fresh in your mind :) You'll understand what the strengths and weaknesses of your new design are, and are better placed to make an improved iteration.

Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).

Re:Annoyances of API Design by dpark on Friday January 29, 2016 @12:34AM (#10993693)
> We definitely need to do that with our APIs and designs (aka. more incremental refactoring).

Not with APIs we've shipped. Then it becomes breaking changes that appear pointless to others. Even when it's logically worth it to go back and fix APIs, it's rarely worth it practically. If no one is using your APIs, then do whatever. If your APIs are popular, you might find yourself in "version next" limbo like so many major projects that redesigned and couldn't convince their users to follow.

Re:Annoyances of API Design by allengeorge on Friday January 29, 2016 @08:51AM (#10995138)
You're absolutely right. FWIW, I think this iterative process should take place before publishing your API. Sometimes a design needs to 'sit' for a month or two and be used a bit before you realize its boundaries: what it does well, and what could be improved. If you're judicious about improvements (i.e. don't rewrite) you'll avoid the second-system effect and put out an API that'll be better than your first attempt. I realize that's not always possible.
Re:Annoyances of API Design by JadeNB on Friday January 29, 2016 @08:37AM (#10995063)
> Not with APIs we've shipped.

To be fair to allengeorge's analogy, writers also rarely edit written works that have already been published.

Re:Annoyances of API Design by blakeyrat on Thursday January 28, 2016 @04:00PM (#10991285)
.net's standard library assemblies are generally excellent. A little verbose, perhaps. And very occassionnally a "what were they thinking?" moment (like WebClient throwing an exception for a 404 response-- fixed in HttpClient.) But overall, excellent.
Re:Annoyances of API Design by int_handler on Thursday January 28, 2016 @05:07PM (#10991780)
Agreed for the most part. My only gripe with the .NET world, and Microsoft's ecosystem in general, is the love for XML (#7 in the article).
Re:Annoyances of API Design by bbarn on Thursday January 28, 2016 @09:30PM (#10993126)
They've generally dropped said love in the newer framework versions.

Also - don't judge MS' love of XML too much, without it, we wouldn't have gotten XMLHttpRequest. :)

Re:Annoyances of API Design by int_handler on Tuesday February 02, 2016 @08:57PM (#11024233)
Good to hear. What are they using for configuration in the newer frameworks instead?

True, XMLHttpRequest was good for the world. My distaste for XML generally stems from some particularly bad experiences I have had working with XML configuration files meant for humans to modify and some particularly poorly-implemented tools for working with said files. :)

Re:Annoyances of API Design by cpeterso on Thursday January 28, 2016 @06:06PM (#10992223)
The Python "Requests" library is known for having a well-designed API, standing on the shoulders of API mistakes made by urllib[123]. :)

http://docs.python-requests.org/

Re:Annoyances of API Design by brianwawok on Thursday January 28, 2016 @03:28PM (#10991032)
Stripe is decent.
Re:Annoyances of API Design by m4yhem on Thursday January 28, 2016 @05:32PM (#10991968)
Qt