Python API Design Principles — ELI5

Imagine a TV remote with 200 buttons, no labels, and a tiny instruction manual in a foreign language. Now imagine one with 10 clearly labeled buttons that do exactly what you expect. The second remote has better API design.

An API in Python is not just web stuff. Every function you write, every class you create — that is an API. It is the surface that other people (or future you) will touch when they use your code. Good design means they can guess how it works before reading any documentation.

The golden rule is: make the easy things easy and the hard things possible. A function to send an email should need just the recipient, subject, and body. Advanced options like CC, attachments, and custom headers should be available but not required for simple cases.

Another important idea is consistency. If one function uses color as a parameter name, do not call it colour in another function and clr in a third. People learn patterns, and breaking patterns forces them to stop and think — which wastes their time.

Good Python APIs also prevent mistakes. Instead of accepting any string and silently failing, they raise clear errors: “Expected an email address, got an empty string.” This is like a plug that only fits one way — you cannot insert it wrong.

The best API feels invisible. Users think about their problem, not about your code. That is the goal.

The one thing to remember: A great Python API lets users do common tasks with almost no learning — make it obvious, consistent, and hard to misuse.