1. Building APIs That Rock
Congratulations: If you’re here, you’re a nerd!
Wednesday, March 4, 2009
2. hi. i’m eaton.
•
• Voting API
eaton@lullabot.com
•
• Token
eaton in #drupal
•
• Form API
twitter.com/eaton
• Render API
• •
@eaton is rambling in the Amazon API
#drupalapi presentation.
•
no puppets yet! Twitter API
Wednesday, March 4, 2009
27. Gentlemen! A Recap!
• Drupal is complicated
• APIs let other code
use your features
Wednesday, March 4, 2009
28. Gentlemen! A Recap!
• Drupal is complicated
• APIs let other code
use your features
• APIs hide complexity
Wednesday, March 4, 2009
29. Gentlemen! A Recap!
• Drupal is complicated
• APIs let other code
use your features
• APIs hide complexity
• APIs get everyone on
the same page
Wednesday, March 4, 2009
30. Screw this.
Let’s make an API.
http://www.flickr.com/photos/djou/2908514697/
Wednesday, March 4, 2009
31. When two modules love
each other very much
The real story of how one API came to be
Wednesday, March 4, 2009
52. What happens when someone adds a new type?
http://www.flickr.com/photos/jayd/3296037643
Wednesday, March 4, 2009
53. What happens when someone adds a new type?
What happens when another person does?
http://www.flickr.com/photos/jayd/3296037643
Wednesday, March 4, 2009
54. What happens when someone adds a new type?
What happens when another person does?
Use enums for lists that won’t change.
http://www.flickr.com/photos/jayd/3296037643
Wednesday, March 4, 2009
55. What happens when someone adds a new type?
What happens when another person does?
Use enums for lists that won’t change.
Use strings for stuff you can’t predict
http://www.flickr.com/photos/jayd/3296037643
Wednesday, March 4, 2009
59. Remember the verbs?
Are you doing things other modules care about?
Wednesday, March 4, 2009
60. Remember the verbs?
Are you doing things other modules care about?
Wednesday, March 4, 2009
61. Remember the verbs?
Are you doing things other modules care about?
Wednesday, March 4, 2009
62. Remember the verbs?
Are you doing things other modules care about?
module_invoke_all()
It’s like party invitations for code
Wednesday, March 4, 2009
64. Remember the nouns?
Are you building data other modules want to change?
Wednesday, March 4, 2009
65. Remember the nouns?
Are you building data other modules want to change?
Wednesday, March 4, 2009
66. Remember the nouns?
Are you building data other modules want to change?
Wednesday, March 4, 2009
67. Remember the nouns?
Are you building data other modules want to change?
drupal_alter()
It’s like passing around the doobie of data
Wednesday, March 4, 2009
77. Stop! Hammertime!
• Identify verbs and nouns
Wednesday, March 4, 2009
78. Stop! Hammertime!
• Identify verbs and nouns
• Layer your verbs to hide
complexity
Wednesday, March 4, 2009
79. Stop! Hammertime!
• Identify verbs and nouns
• Layer your verbs to hide
complexity
• Account for new uses
Wednesday, March 4, 2009
80. Stop! Hammertime!
• Identify verbs and nouns
• Layer your verbs to hide
complexity
• Account for new uses
• Broadcast events via
hooks
Wednesday, March 4, 2009
81. Stop! Hammertime!
• Identify verbs and nouns
• Layer your verbs to hide
complexity
• Account for new uses
• Broadcast events via
hooks
• Let modules alter data
Wednesday, March 4, 2009
85. The Lone Ranger
• Reinventing the wheel
Wednesday, March 4, 2009
86. The Lone Ranger
• Reinventing the wheel
• Ignoring conventions
Wednesday, March 4, 2009
87. The Lone Ranger
• Reinventing the wheel
• Ignoring conventions
• Ignoring related APIs!
Wednesday, March 4, 2009
88. The Lone Ranger
• Reinventing the wheel
• Ignoring conventions
• Ignoring related APIs!
• Common for newcomers, or obsessives
Wednesday, March 4, 2009
91. Invisible Assumptions
• Assuming the global $user
• Checking arg(0)…
Wednesday, March 4, 2009
92. Invisible Assumptions
• Assuming the global $user
• Checking arg(0)…
• Assuming logged in users…
Wednesday, March 4, 2009
93. Invisible Assumptions
• Assuming the global $user
• Checking arg(0)…
• Assuming logged in users…
• Common with UI-bound APIs
Wednesday, March 4, 2009
95. Helping them to death
• “I’ll set the breadcrumb while I’m at it...”
Wednesday, March 4, 2009
96. Helping them to death
• “I’ll set the breadcrumb while I’m at it...”
• “And I’ll send an email, too!”
Wednesday, March 4, 2009
97. Helping them to death
• “I’ll set the breadcrumb while I’m at it...”
• “And I’ll send an email, too!”
• “And add these links, and…”
Wednesday, March 4, 2009
98. Helping them to death
• “I’ll set the breadcrumb while I’m at it...”
• “And I’ll send an email, too!”
• “And add these links, and…”
• Common when an API grows out of a
specific use case, or an existing module
Wednesday, March 4, 2009
100. Leaky Abstraction
• “Just use this function…”
Wednesday, March 4, 2009
101. Leaky Abstraction
• “Just use this function…”
• ...And learn everything underneath it.
Wednesday, March 4, 2009
102. Leaky Abstraction
• “Just use this function…”
• ...And learn everything underneath it.
• Common in complex problem domains
Wednesday, March 4, 2009
103. Leaky Abstraction
• “Just use this function…”
• ...And learn everything underneath it.
• Common in complex problem domains
• Simplify, or get out of the way
Wednesday, March 4, 2009
104. Leaky Abstraction
• “Just use this function…”
• ...And learn everything underneath it.
• Common in complex problem domains
• Simplify, or get out of the way
• Sometimes, problems are just complicated.
Wednesday, March 4, 2009
106. Fake Flexibility
• “Oh, you can save any data…” (votingapi)
Wednesday, March 4, 2009
107. Fake Flexibility
• “Oh, you can save any data…” (votingapi)
• “Oh, there’s a hook for that…” (blogapi)
Wednesday, March 4, 2009
108. Fake Flexibility
• “Oh, you can save any data…” (votingapi)
• “Oh, there’s a hook for that…” (blogapi)
• Build 3 test implementations
Wednesday, March 4, 2009
109. Fake Flexibility
• “Oh, you can save any data…” (votingapi)
• “Oh, there’s a hook for that…” (blogapi)
• Build 3 test implementations
• Step through different use cases
Wednesday, March 4, 2009
111. Mission Creep
• Even worse than feature creep
Wednesday, March 4, 2009
112. Mission Creep
• Even worse than feature creep
• Common with “solve-a-big-problem” APIs
Wednesday, March 4, 2009
113. Mission Creep
• Even worse than feature creep
• Common with “solve-a-big-problem” APIs
• Focus, focus, focus.
Wednesday, March 4, 2009
114. Mission Creep
• Even worse than feature creep
• Common with “solve-a-big-problem” APIs
• Focus, focus, focus.
• Split into complementary APIs
Wednesday, March 4, 2009
116. Dependency Soup
• The flip side of mission creep
Wednesday, March 4, 2009
117. Dependency Soup
• The flip side of mission creep
• Focus, focus, focus!
Wednesday, March 4, 2009
118. Dependency Soup
• The flip side of mission creep
• Focus, focus, focus!
• Make the dependencies optional
Wednesday, March 4, 2009
119. Dependency Soup
• The flip side of mission creep
• Focus, focus, focus!
• Make the dependencies optional
• Pray for a package manager
Wednesday, March 4, 2009
122. Oh, the Recappery!
• Cooperate
• Don’t assume too much
Wednesday, March 4, 2009
123. Oh, the Recappery!
• Cooperate
• Don’t assume too much
• Don’t be pushy
Wednesday, March 4, 2009
124. Oh, the Recappery!
• Cooperate
• Don’t assume too much
• Don’t be pushy
• Simplify or step aside
Wednesday, March 4, 2009
125. Oh, the Recappery!
• Cooperate
• Don’t assume too much
• Don’t be pushy
• Simplify or step aside
• Test your extensions
Wednesday, March 4, 2009
126. Oh, the Recappery!
• Cooperate
• Don’t assume too much
• Don’t be pushy
• Simplify or step aside
• Test your extensions
• Stay focused
Wednesday, March 4, 2009
You were promised puppets. Also, magic.
Unfortunately, you’ve been deceived. There are no puppets.
The ends justify the means: APIs are Drupal’s lifeblood.
When I started using Drupal, it was a little goofy, but fundamentally simple.
Core. Some modules (gallery? event? done!)
Maybe a custom module and a theme if you were REALLY crazy.
When I started using Drupal, it was a little goofy, but fundamentally simple.
Core. Some modules (gallery? event? done!)
Maybe a custom module and a theme if you were REALLY crazy.
Today, lots and lots of smaller modules
Image == Views, CCK, FileField, ImageField, ImageCache, ImageAPI, Custom Breadcrumbs.
Flexibility vs. Complexity
All the pieces have to work with each other! And that’s where APIs come in.
Today, lots and lots of smaller modules
Image == Views, CCK, FileField, ImageField, ImageCache, ImageAPI, Custom Breadcrumbs.
Flexibility vs. Complexity
All the pieces have to work with each other! And that’s where APIs come in.
The pull between functionality and flexibility
Building code that does stuff, APIs that let other code control it, and UIs that let users configure/control
The pull between functionality and flexibility
Building code that does stuff, APIs that let other code control it, and UIs that let users configure/control
Imagine a Drupal module as a giant pile of money.
Mmmmmmmmmmm.
Each of those awesome features is like a crisp $20.
Imagine “Code” -- other Drupal modules -- as users who can’t click on anything. All they can do is call other functions.
Can they use your module?
Could an install profile set up your module automatically?
Can someone turn off your UI entirely, and make it automatic?
Can someone build a new UI for your module?
Imagine a Drupal module as a giant pile of money.
Mmmmmmmmmmm.
Each of those awesome features is like a crisp $20.
Imagine “Code” -- other Drupal modules -- as users who can’t click on anything. All they can do is call other functions.
Can they use your module?
Could an install profile set up your module automatically?
Can someone turn off your UI entirely, and make it automatic?
Can someone build a new UI for your module?
Imagine a Drupal module as a giant pile of money.
Mmmmmmmmmmm.
Each of those awesome features is like a crisp $20.
Imagine “Code” -- other Drupal modules -- as users who can’t click on anything. All they can do is call other functions.
Can they use your module?
Could an install profile set up your module automatically?
Can someone turn off your UI entirely, and make it automatic?
Can someone build a new UI for your module?
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
The ATM is a metaphor: it’s a basic way of controlling things that can be used externally.
Flag
Organic Groups
node_save()
Something complicated can be simplified by putting a buffer between it, and you.
ImageAPI
Messaging
Visitor
cache_get() and cache_set()
Something complicated can be simplified by putting a buffer between it, and you.
ImageAPI
Messaging
Visitor
cache_get() and cache_set()
The value in credit cards isn’t that they’re thin and plastic
It’s that everyone uses them, so the problem of “IOUs” and “Store credit” and “Pay you back later” are all handled with this.
Everyone’s on the same page, so they can get on to solving other problems
The value in credit cards isn’t that they’re thin and plastic
It’s that everyone uses them, so the problem of “IOUs” and “Store credit” and “Pay you back later” are all handled with this.
Everyone’s on the same page, so they can get on to solving other problems
History of VotingAPI - 2005
Was making a community site that needed to rate comments AND nodes, with a nice flash widget AND a nice
Picked the one that seemed best and shamelessly ripped its guts out
History of VotingAPI - 2005
Was making a community site that needed to rate comments AND nodes, with a nice flash widget AND a nice
Picked the one that seemed best and shamelessly ripped its guts out
History of VotingAPI - 2005
Was making a community site that needed to rate comments AND nodes, with a nice flash widget AND a nice
Picked the one that seemed best and shamelessly ripped its guts out
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Voila! VotingAPI 1.0 Beta! Simple, but effective.
How to start thinking about it like an API?
Find the nouns
Find the verbs
This is similar to building good classes in OOP languages like Java. Those guys think about APIs all freakin’ day.
Discussions on drupal.org, working with other developers to gather use cases.
Not flexible enough! My my noun weren’t precise enough…
Additional data: “Tag” for multiple criteria voting
My verbs were too broad!
Sub-functions.
Building in layers is important
Discussions on drupal.org, working with other developers to gather use cases.
Not flexible enough! My my noun weren’t precise enough…
Additional data: “Tag” for multiple criteria voting
My verbs were too broad!
Sub-functions.
Building in layers is important
Discussions on drupal.org, working with other developers to gather use cases.
Not flexible enough! My my noun weren’t precise enough…
Additional data: “Tag” for multiple criteria voting
My verbs were too broad!
Sub-functions.
Building in layers is important
Discussions on drupal.org, working with other developers to gather use cases.
Not flexible enough! My my noun weren’t precise enough…
Additional data: “Tag” for multiple criteria voting
My verbs were too broad!
Sub-functions.
Building in layers is important
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Feedback: Vote on a 1-100 scale! Or vote with “points” like Digg! And getting results is too slow -- sorting and filtering with them takes complex SQL!
The “vote” noun has a ‘value type’ now. What does the number MEAN?
New noun: “Results”, new verb “Recalculate”
Now have votes that can be set, and retrieved. Results that can be recalculated and retrieved. “Value type” lets modules use it in unanticipated ways, too!
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
Holy crap, someone hates me.
Quick show of hands -- what’s wrong with this?
We’ve covered the basics of letting other modules “steer” your code.
The next step - giving your module points of expansion
Several common patterns in Drupal
