Like APIs, Python and telling everybody to like the Python and APIs.

How we design APIs today:

  • Somebody decides he needs API
  • Developers brainstorm around whiteboard
  • Couple of months later, API sees the world.
  • Clients doesn’t like it. Nobody asked them.

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.