===============
API Design Tips
===============

Daniel Lindsley

What?
=====

* Not HTTP APIs
* Programmatic APIs
* Think libraries
    * especially ones you hand off to other people…

Why?
====

* Think about how many times you've started with someone else's library…
* Used it some…
* Then got really upset and frustrated

* Other people use your code all the time

* Nice APIs begets *Happiness*
* Happiness begets *Recommendations*
* Recommendations beget *Users/Community*

Philosophy
==========

* You can't make everyone happy by default
    * You should still have sane defaults
* But *more* people will be happy if they can tweak it
    * You can bet they'll need to
* And most people will be happy if it's easy to tweak
* No copy-paste should be needed
    * Boilerplate sucks
* They shouldn't have to constantly refer to the docs
    * Especially not for things they use *all* the freaking time
* Good docs matter
    * Saves you (support) & them (implementation) time. Everyone wins
* Real World use is the best sanity check
* Someone is going to something weird/insane with your code
    * It's inevitable, so design for it up front

Approaches on Design
====================

* Common Methodologies:
    * Bottom-up
        * small components over time that eventually all work together in the final product
    * Top-down
        * build the ideal code at first, then writing the underlying code to make the ideal real
* Bottom-up sucks
    * sure, you built little pieces that work
    * but do they really work well together?
        * likely not
        * how is php formed
* Top-down feels better
    * everything fits together right
    * less duplication
    * helps you to resist the urge to duct tape things together
* With some instant TDD, you get your tests started from the get-go
    * fewer massive, painful refactories down the road

Things You Should Do
====================

* Small components
    * worked for UNIX, it'll work for you
* Composition >= Inheritance
    * Why do the work yourself when you can delegate?
* Reflection
    * If data can flow one way, add the opposite
* Broad familiarity
    * If it's a similar task to something else they know, mimic that something else
* Narrow familiarity
    * Call signatures matter
* Assume the worst
    * Don't code for just the easy case

Things You Should Not Do
========================

* Stop at a low level
* Wildly different return values
* Useless "implementation" code
* If it's difficult to test...

Django-specific Topics
======================

* Pluggable backend all the things
* Internationalize all the things
* Dynamically loaded classe/code
    * 60% more error-handling, every time
* Declarative syntax
    * Metaclasses: call your doctor if headaches last more than 4 hours
* *Don't* metaclass all the things
* The ORM
    * Love it or hate it, there's some great learning opportunities there
* Decrease reliance on `self`
* Resist the urge to magic
    * Be explicit *first*, then add shortcuts (which can be a little more magical)

In Conclusion
=============

* Use the golden rule
* Consistency is key
* Plan for the worst & include sweet shortcuts
* Make something that you love and make it better