HN Theater @HNTheaterMonth

⬐ sarcasmatwork

This is from 2007... is this even relevant anymore?

⬐ djmips

I haven't watched the talk so I'm not sure I follow why an older talk wouldn't be relevant just because it's older.

Original video, on Google's channel: https://youtu.be/aAb7hSCtvGw

Here are some of my favorites:

How To Design A Good API and Why it Matters https://www.youtube.com/watch?v=aAb7hSCtvGw

Agile Methods The Good, the Hype and the Ugly https://www.youtube.com/watch?v=ffkIQrq-m34&t=420s

⬐ seanmcdirmid

I still find that the Java Collection Library is one of the best design’s out there, collections are something that modern languages still shockingly get wrong (e.g. .net, JavaScript). Bloch really knows what he’s talking about.

⬐ maxxxxx

I thought .NET isn't that bad especially with LINQ. In what way is Java better?

⬐ pjmlp

For a long time, the set of collection classes, which had more variety, and parallel programming support.

Now .NET also has TPL, immutable collections.

Also regardless of what one might think of Swing or JavaFX, at least they are there.

On .NET side, there isn't yet a GUI framework that will work without changes across all implementations, Xamarin might eventually be it, but only after 3.0 release.

⬐ seanmcdirmid

In .net, you have to decide what optional library you are going to use to make up for an extremely lacking standard library. Sometimes what you need simply isn’t easy to find and you are stuck rolling your own (e.g. head and last operations on tree sets). The JCL is very complete in comparison.

For UI, WPF is pretty good, and .net wasn’t meant to be cross platform anyways.

⬐ amelius

An API should always take a transaction object as one of its parameters. This allows you to safely run multiple services inside a single atomic transaction. Without this possibility, complexity inevitably ensues.

⬐ arcbyte

The service is the transaction boundary. If you need "transactions" across services then you need to start looking at Sagas/Processes.

⬐ chopin

Could you give an example under which circumstances you'd want this?

The last thing I'd want to give an API is such an object in order to do something for me (like committing).

I'd had more than one occasion where I had to pass an InputStream to an API only to find out that it kindly closed it for me. This is unfortunate if you want to pass a ZipInputStream: as it does not hand out separate streams for entries, closing the stream does close the entire stream, not the entry passed.

⬐ amelius

> The last thing I'd want to give an API is such an object in order to do something for me (like committing).

That's not what the transaction is supposed to be passed for. It's simply passed as a way to ensure that state changes are atomic.

Basically, if you're using transactions inside a program, passing them between functions, that's the same concept. Except now you're passing the transaction to an API.

⬐ chopin

How would the API ensure this when getting passed a transaction? I fail to understand this. A transaction has two main methods, commit and rollback (do I miss some?). I'd never want an API to call those. That's up to the caller.

⬐ jeffreyrogers

I think the person you're replying to means something like "context" rather than what you're calling a transaction. So you'd give the function all the context it needs to atomically perform whatever update it needs to perform. That's my best guess at least.

Of course, part of the reason we don't do this is performance: it costs a lot to copy around all the state you need to perform an action.

⬐ amelius

You can call it a transaction context, but it's really a transaction that's being passed, i.e., you're saying to the called function: every change you make is happening within this transaction I'm passing you here.

It's nothing new of course. What I'm saying here is that APIs should support the concept.

⬐ amelius

When you manipulate the state of something (e.g. database or memory), then in a transactional system you have to specify in which transaction the change is supposed to occur.

So besides commit and rollback, a transaction has a "change" method, if you'd like to look at it that way. The change method is what makes transactions useful.

And the API function is indeed supposed to call only "change", not "commit" or "rollback".

⬐ chopin

https://docs.oracle.com/javaee/6/api/javax/persistence/Entit... doesn't have this. Could you point to a transaction (preferably in Java) which permits a "change"?

⬐ sk5t

I am also baffled as to what this "change" operation is meant to suggest.

Enlisting possibly-unrelated operations in a common transaction is a good tool to have in the toolbox, although it is a tad hairy to bake that into each method signature. Spring's TransactionTemplate presents an alternate approach.

⬐ None

None

⬐ anonymousDan

Another cool paper related to API design is "The Scalable Commutativity Rule: Designing Scalable Software for Multicore Processors". Basically discusses the impact mistakes in an API design can have on performance/scalability.

a.) On java - one hour talk but good:

* How To Design A Good API and Why it Matters https://www.youtube.com/watch?v=aAb7hSCtvGw

b.) General code structure - dont to read it cover to cover unless you like to, you will die of boredom, but definitely have a look in library. It will help you to think about code structure right way.

* Refactoring: Improving the Design of Existing Code * Code Complete

c.) Object Oriented Programming

* Design Patterns: Elements of Reusable Object-Oriented

The three books I recommended are older, but not much changed in basics of object oriented programming. They are well readable. I would also recommend to read something on functional programming, mostly so that you see another approach too and thus wont go too far with object design where it does not suits.

d.) 8.) I read awesome book on estimations, I really really hope it is this one:

* Software Estimation: Demystifying the Black Art

tldr: There is difference between negotiation and estimation, make sure you know which you are doing. Split it into smaller tasks and then estimate minimum, maximum and most likely. Then calculate (min+4*likely+max)/6. Surprisingly, it works and is faster then do one estimate. It is also more precise then anything else I tried. I really hope I shown you right book.

e.) On Spring and rest, I would recommend to read documentation and write own code. I don't recall a book that would blow my mind, so I guess any will do.

f.) For general "latest tech" learning, I like https://dzone.com/ site. There are mostly techie tech articles - they are not news site like hacker news or arstechnica. They have "zones" for different interests, java zone is here: https://dzone.com/java-jdk-development-tutorials-tools-news . Pick up zones and make a habit of reading one article a week or something like that.

⬐ siropa

Bookmarked :) Thankyou!

⬐ madhusharma

Nice Post to Understand for designing good API!

  How To Design A Good API and Why it Matters [0]
  The Principles of Clean Architecture [1]
  The State of the Art in Microservices by Adrian Cockcroft [2]
  "The Mess We're In" by Joe Armstrong [3]

[0] https://www.youtube.com/watch?v=aAb7hSCtvGw

[1] https://www.youtube.com/watch?v=o_TH-Y78tt4

[2] https://www.youtube.com/watch?v=pwpxq9-uw_0

[3] https://www.youtube.com/watch?v=lKXe3HUG2l4

⬐ zerognowl

+1 for Joe Armstrong's talk. Very funny, but uncomfortably true

⬐ panic

On the subject of API design, this talk is also quite good: https://www.youtube.com/watch?v=ZQ5_u8Lgvyk

Joshua Bloch: How to design a good API and why it matters

https://www.youtube.com/watch?v=aAb7hSCtvGw

How to Design A Good API and Why it Matters: https://www.youtube.com/watch?v=aAb7hSCtvGw

Related slides: http://static.googleusercontent.com/media/research.google.co...

Don't miss Joshua Bloch (from "Effective Java" fame) great presentation: How to design a good API and why it matters https://www.youtube.com/watch?v=aAb7hSCtvGw

and the accompanying slides: http://static.googleusercontent.com/media/research.google.co...

⬐ philbo

+1, strongly agree.

I've recommended this talk to numerous colleagues over the years, always with extremely positive feedback. And I've re-watched it myself 3 or 4 times as a refresher before starting out on a new API.

It's easily in my top ten favourite programming talks. If anyone hasn't watched it, I can't recommend it highly enough.

The Little Manual of API Design (Trolltech/Nokia): http://people.mpi-inf.mpg.de/~jblanche/api-design.pdf

How to Design a Good API and Why it Matters (Josh Bloch): http://static.googleusercontent.com/media/research.google.co... https://www.youtube.com/watch?v=aAb7hSCtvGw

⬐ hinkley

Ugh. Can someone please point me to a good API designed by Josh Bloch? The handful I know of have all been a giant pain in my backside.

He keeps writing like he's an expert and I am still waiting for evidence to back that up,

⬐ udkl

* You have one chance to get the API right

* API’s can make or break the company

* Everyone is an API designer. If you program, you are an API designer.

* Good API: Easy to use, learn, hard to misuse, just powerful enough, easy to evolve, appropriate for the audience (API terminology)

* Process

- Gather requirements - Be Skeptical - Hear the un-said.

- Convert requirements to use-cases

- Start with a short spec - ideally 1 page

-- Don’t create a long spec first time around - it gets associated with the ego and then iterate

- bounce it off of the stakeholders

* Write to your API early and often. Basically, write tests early. - These probably will live on to become examples on how to use the API - Make sure these are exemplary as the examples will be used by consumers to base off their code.

* Maintain realistic expectations - You won’t be able to please everyone - Aim to displease everyone equally

* Expect to make mistakes - API design is hard - Expect the API to evolve

* Principles of good API design: - Should do one thing and do it well. - Should be easy to explain. - Should be easy to name

* Should be as small as possible but not smaller - When in doubt, leave it out. - It’s easier to add it later than to remove it.

* Implementation should not impact API

- details confuse users

- inhibit freedom to change an implementation

--- eg: catching SQL exceptions by the client

-- Do not let implementation detail leak into the API

--- Eg: implements serializable - all private fields are now public after serialization

* Minimize accessibility of fields

- Make classes, fields as private as possible

- public classes should not have any public fields, with the exception of constants

- Minimizes coupling

* Names matter

- Names should be self-explanatory

- Be consistent

- Be regular- strive for symmetry

--- If key and entry are two attributes, and addKey and removeKey are methods on ‘key’ then there should be ‘addEntry’ and ‘removeEntry’

* Document religiously

- Document every class, interface, method, constructor, parameter and exception.

- Method documentation : contract tween method and it’s clients : pre-conditions, post-conditions, side-effects

- Parameters : indicate ownership(can I modifiy it ?), units (size of blocks in bytes), form (String : XML ? json)

* Document state space religiously

---- 37 minutes in the video ---- To be continued...

I highly recommend the following talk by Joshua Bloch: "How to design a good API and why it mattes" [1].

Key points:

- When in doubt, leave it out - you can never remove things from an API but always add to it.

- Write several clients of the API to get a good feel how its used. Three is usually enough, one is not.

[1] https://www.youtube.com/watch?v=aAb7hSCtvGw

I highly recommend this ~hour long talk given by Josh Bloch a few years ago, it is quite good and gives plenty of concrete examples: https://www.youtube.com/watch?v=aAb7hSCtvGw

⬐ relaunched

Thanks!

https://www.youtube.com/watch?v=aAb7hSCtvGw

Summary of the links shared here:

http://blip.tv/clojure/michael-fogus-the-macronomicon-597023...

http://blog.fogus.me/2011/11/15/the-macronomicon-slides/

http://boingboing.net/2011/12/28/linguistics-turing-complete...

http://businessofsoftware.org/2010/06/don-norman-at-business...

http://channel9.msdn.com/Events/GoingNative/GoingNative-2012...

http://channel9.msdn.com/Shows/Going+Deep/Expert-to-Expert-R...

http://en.wikipedia.org/wiki/Leonard_Susskind

http://en.wikipedia.org/wiki/Sketchpad

http://en.wikipedia.org/wiki/The_Mother_of_All_Demos

http://io9.com/watch-a-series-of-seven-brilliant-lectures-by...

http://libarynth.org/selfgol

http://mollyrocket.com/9438

https://github.com/PharkMillups/killer-talks

http://skillsmatter.com/podcast/java-jee/radical-simplicity/...

http://stufftohelpyouout.blogspot.com/2009/07/great-talk-on-...

https://www.destroyallsoftware.com/talks/wat

https://www.youtube.com/watch?v=0JXhJyTo5V8

https://www.youtube.com/watch?v=0SARbwvhupQ

https://www.youtube.com/watch?v=3kEfedtQVOY

https://www.youtube.com/watch?v=bx3KuE7UjGA

https://www.youtube.com/watch?v=EGeN2IC7N0Q

https://www.youtube.com/watch?v=o9pEzgHorH0

https://www.youtube.com/watch?v=oKg1hTOQXoY

https://www.youtube.com/watch?v=RlkCdM_f3p4

https://www.youtube.com/watch?v=TgmA48fILq8

https://www.youtube.com/watch?v=yL_-1d9OSdk

https://www.youtube.com/watch?v=ZTC_RxWN_xo

http://vimeo.com/10260548

http://vimeo.com/36579366

http://vimeo.com/5047563

http://vimeo.com/7088524

http://vimeo.com/9270320

http://vpri.org/html/writings.php

http://www.confreaks.com/videos/1071-cascadiaruby2012-therap...

http://www.confreaks.com/videos/759-rubymidwest2011-keynote-...

http://www.dailymotion.com/video/xf88b5_jean-pierre-serre-wr...

http://www.infoq.com/presentations/Are-We-There-Yet-Rich-Hic...

http://www.infoq.com/presentations/click-crash-course-modern...

http://www.infoq.com/presentations/miniKanren

http://www.infoq.com/presentations/Simple-Made-Easy

http://www.infoq.com/presentations/Thinking-Parallel-Program...

http://www.infoq.com/presentations/Value-Identity-State-Rich...

http://www.infoq.com/presentations/We-Really-Dont-Know-How-T...

http://www.mvcconf.com/videos

http://www.slideshare.net/fogus/the-macronomicon-10171952

http://www.slideshare.net/sriprasanna/introduction-to-cluste...

http://www.tele-task.de/archive/lecture/overview/5819/

http://www.tele-task.de/archive/video/flash/14029/

http://www.w3.org/DesignIssues/Principles.html

http://www.youtube.com/watch?v=4LG-RtcSYUQ

http://www.youtube.com/watch?v=4XpnKHJAok8

http://www.youtube.com/watch?v=5WXYw4J4QOU

http://www.youtube.com/watch?v=a1zDuOPkMSw

http://www.youtube.com/watch?v=aAb7hSCtvGw

http://www.youtube.com/watch?v=agw-wlHGi0E

http://www.youtube.com/watch?v=_ahvzDzKdB0

http://www.youtube.com/watch?v=at7viw2KXak

http://www.youtube.com/watch?v=bx3KuE7UjGA

http://www.youtube.com/watch?v=cidchWg74Y4

http://www.youtube.com/watch?v=EjaGktVQdNg

http://www.youtube.com/watch?v=et8xNAc2ic8

http://www.youtube.com/watch?v=hQVTIJBZook

http://www.youtube.com/watch?v=HxaD_trXwRE

http://www.youtube.com/watch?v=j3mhkYbznBk

http://www.youtube.com/watch?v=KTJs-0EInW8

http://www.youtube.com/watch?v=kXEgk1Hdze0

http://www.youtube.com/watch?v=M7kEpw1tn50

http://www.youtube.com/watch?v=mOZqRJzE8xg

http://www.youtube.com/watch?v=neI_Pj558CY

http://www.youtube.com/watch?v=nG66hIhUdEU

http://www.youtube.com/watch?v=NGFhc8R_uO4

http://www.youtube.com/watch?v=Nii1n8PYLrc

http://www.youtube.com/watch?v=NP9AIUT9nos

http://www.youtube.com/watch?v=OB-bdWKwXsU&playnext=...

http://www.youtube.com/watch?v=oCZMoY3q2uM

http://www.youtube.com/watch?v=oKg1hTOQXoY

http://www.youtube.com/watch?v=Own-89vxYF8

http://www.youtube.com/watch?v=PUv66718DII

http://www.youtube.com/watch?v=qlzM3zcd-lk

http://www.youtube.com/watch?v=tx082gDwGcM

http://www.youtube.com/watch?v=v7nfN4bOOQI

http://www.youtube.com/watch?v=Vt8jyPqsmxE

http://www.youtube.com/watch?v=vUf75_MlOnw

http://www.youtube.com/watch?v=yJDv-zdhzMY

http://www.youtube.com/watch?v=yjPBkvYh-ss

http://www.youtube.com/watch?v=YX3iRjKj7C0

http://www.youtube.com/watch?v=ZAf9HK16F-A

http://www.youtube.com/watch?v=ZDR433b0HJY

http://youtu.be/lQAV3bPOYHo

http://yuiblog.com/crockford/

⬐ ricardobeat

And here are them with titles + thumbnails:

http://bl.ocks.org/ricardobeat/raw/5343140/

⬐ waqas-

how awesome are you? thanks

⬐ Expez

Thank you so much for this!

⬐ X4

This is cool :) Btw. the first link was somehow (re)moved. The blip.tv link is now: http://www.youtube.com/watch?v=0JXhJyTo5V8

Single best is difficult, here are some favourites of mine:

"You and your research" by Richard Hamming:

http://www.youtube.com/watch?v=a1zDuOPkMSw

"How to design a good API and why it matters" by Joschua Bloch:

http://www.youtube.com/watch?v=aAb7hSCtvGw

Google TechTalk on Git by Linus Torvalds:

http://www.youtube.com/watch?v=4XpnKHJAok8

All talks ever given by Alan Kay, for example:

http://www.youtube.com/watch?v=oKg1hTOQXoY

⬐ stblack

Double thumbs-up to Google TechTalk on Git by Linus Torvalds.

I'm building a public API in my current job and, a few weeks ago, I was scouting around for the good API design advice. Absolutely far and away the best resource that I found was this Google TechTalk by Joshua Bloch:

http://www.youtube.com/watch?v=aAb7hSCtvGw

If you're interested in the topic and haven't seen it yet, I urge you to do so ASAP.

⬐ tomgallard

Building the API for Pwinty (http://www.pwinty.com) I found the Dropbox API docs to be a really good example of how to structure your documentation - http://www.dropbox.com/developers/reference/api

All the resources are documented in the same way, it is nicely formatted, and easy to understand.

⬐ masklinn

Parse's blog has a pretty good article on documenting APIs[0], with links to a number of nicely one API documentations (not dropbox's, but Github's, Stripe's, Backbone's, Mailgun's and their own)

[0] http://blog.parse.com/2012/01/11/designing-great-api-docs/

How about this to start? "How To Design A Good API and Why it Matters" -- a great talk by Joshua Bloch (also the author of "Effective Java")

http://www.youtube.com/watch?v=aAb7hSCtvGw

Obviously, this is marketing rather than a serious treatment of the topic. It seems to basically say: "in order to design a system, you should have a regular undergraduate Computer Science education" which seems maybe like a prerequisite (and maybe informative about their hiring process) but not very useful.

However, for what it's worth, the two best resources I've seen for systems design are:

Hints for Computer System Design: http://cseweb.ucsd.edu/classes/wi08/cse221/papers/lampson83....

How to Design a Good API: http://www.youtube.com/watch?v=aAb7hSCtvGw

What else should be in this bibliography?

⬐ basugasubaku

That's not what the article says at all. In fact, a CS education is likely not good enough. There are plenty of new graduates who do not know much about, e.g., IPC or have a good feel for real world performance numbers. The article rightly recommends working on actual systems including OSS projects.

Not specifically about web service APIs, but you might enjoy this talk by Joshua Bloch [1]:

"How To Design A Good API and Why it Matters": http://www.youtube.com/watch?v=aAb7hSCtvGw

[1] http://en.wikipedia.org/wiki/Joshua_Bloch

⬐ darylteo

Thanks

Also noteworthy is the "How to Design a Good API & Why it Matters" talk

video: http://www.youtube.com/watch?v=aAb7hSCtvGw

pdf: http://lcsd05.cs.tamu.edu/slides/keynote.pdf

Joshua Bloch gave a good presentation on API design, you might have seen this before. Here is the link - http://www.youtube.com/watch?v=aAb7hSCtvGw

Mostly along those lines will make a presentation useful and interesting. Not sure whats the time limit for your presentation but real life example would keep the audience more interactive or building something on the fly from ground up.

It's the first result on google:

http://www.youtube.com/watch?v=aAb7hSCtvGw

I also like this josh bloch google tech talk video "How to design a good API and why it matters.": http://www.youtube.com/watch?v=aAb7hSCtvGw