Like APIs, Python and telling everybody to like the Python and APIs.
How we design APIs today:
API provides are not doing what API customers want.
API is interface to data for client developers.
Developers are usually humans :) They want debugging, How tos, examples, …
There can be different naming conventions, idioms, approaches… how to handle these differences between API.
When designing APIs: communicate, design, prototype, ask, iterate. Let clients be part of process.
API blueprint - markdown file - human writeable/readable, versionable, understandable by both techies and non-techies.
Can be also parsed to tree and e.g. generate documentation
You can get immediate feedback from mocks provided by APIary based on API blueprint.
Lot of open-source around it - not vendor-locked.