Building APIs that Rock (DrupalCon 2009 notes)
9:00 AM, 2009-03-04
- let other code use your features
- hide complexity
- Better to write modules that use underlying functions than "pretending" to be a user and using forms
- hides whether ImageMagick or GD tools (or other lib) is being used
- provides "rotate" "scale" "crop" Messaging
- abstracts /how/ messages are being sent
- cache_get, cache_set (inside Drupal)
- provide simple interface to hide method underneath (memcache, etc)
- Agreement about how things get done
Example: Creating VotingAPI
- started by tearing apart someone else's module
- find nouns: votes
- find verbs: get / set
- don't use enums and hard-coded numbers unless you know it's something that won't change
- use strings to allow others to make their own new type
- well placed hooks allow other people to do the hard work for you!
- drupal_alter(): "it's like passing around the doobie of data" : everybody gets a chance. (you don't have to...)"
- who wants to hijack this before it hits the page?
- let other modules have a chance to change or add more data
- "template" design pattern
- "if you build it they will hook"
- layer verbs to hide complexity
- account for new users
7 deadly sins
- Lone Ranger (reinvents wheel, ignores conventions, ignores related apis... common to newcomers
- invisible Assumptions (assuming the global $user, checking arg(0), assuming logged-in users... common to UI-centric modules
- Helping them to Death ("while i'm at it, I'll set the breadcrumb, send an email, and add links, and... common to bloated modules
- Leaky Abstraction ("just use this function... and learn everything that's underneath it! ... common in complex problem domains. Simplify! Assume sensible defaults, and get out of the way when appropriate
- Fake Flexibility (Providing hooks that don't really provide the functionality they portray
- Mission Creep (even worse than feature creep .. common with "solve a big problem APIs. Split it into smaller APIs!
- Dependency Soup (Flip-side of Mission Creep. Focus focus focus! Make dependencies optional, pray for a package manager in Drupal
Rules of Thumb
- don't assume too much
- do't be pushy
- simplify or step aside
- test your extensions
- stay focused