This hands-on presentation teaches participants how to design APIs that are simple and consistent to use. If your API is easy to use then it will be more likely to be adopted and will speed product delivery. This presentation will be given at BYU during the FamilySearch Developers Conference 2014

1. API Simplicity == Speed
Designing APIs That Are Easy and Fun to Use
Harold Madsen, API Director @ Ancestry.com
Positions: Platform Initiative + External APIs + Notification + Community
Speaker: API Strategy (San Fran), RootsTech (SLC), FamilySearch DevCon (BYU)
Publisher: InformationWeek.com
September 18, 2014

2. Agenda
I. Design Concepts
II. Design Principles
III. REST Standards
IV. Client Proxy Standards
V. Sum It Up
Frederick Douglass, abolitionist

3. 3
Design Concepts
Before we talk API standards, let’s cover some concepts

4. Design Affordance
How A Physical Item
Is Designed
Instructs
How It’s Used
Psychologist James J. Gibson originally introduced the term in his
1977 article "The Theory of Affordances“ and explored it more fully
in his book The Ecological Approach to Visual Perception in 1979
4

5. Design Matters
www.baddesigns.com
5

6. Design Matters for APIs Too
• Good, Bad and the Ugly
• Used a Bad API? What is it like going to work each day?
6
AddressVerify
Callback
DoCapture
DoVoid
MassPayment
GetBalance
TransactionSearch
UpdateRecurringPaymentProfile
SetExpressCheckOut
RefundTransaction
Etc.
account.GetBalance(…)
payments.GetInvoice(…)
payments.Void(invoiceId)
payments.Search(…)
Etc.

7. API Smell Test
• Does It Pass the Smell Test?
• Methods
 tSndMl
 MyEventType -> let’s use verbs
• Parameters
 SendMail(var1, var2, var3, var4, var5, var6, var7, var8);
- Maintainability, extensibility, and backwards/forwards compatibility
• URLs
 https://somedomain.com/cgi-bin/prod/load_survey_mysql?rater_id={id}
7 • Service Name: OREM

8. A Pragmatic Approach to Great APIs
8
- Brian Mulloy
make for happy developers
“RESTful API Design”
@landlessness
Consistent APIs
Design for simplicity
and ease of use
Keep the client (developer)
in mind

9. Programs must be written
for people to read, and
only incidentally for
machines to execute
9
“
- Abelson & Sussman
Structure & Interpretation
Of Computer Programs

10. Design Principles
What are Ancestry.com’s guiding principles?
10

11. Design Guidelines
• Design with Developer in Mind
• Be Consistent
 help developers “guess the answer”
• Your API should be Obvious
 what it is and how to use it
• Good Designs Take Time
 you have permission
• Decide as a Group
 2+ heads make better decisions
11 • Avoid method-driven approach

12. Consistency
Help Developers Anticipate Your Thinking
• Standard URL Patterns
 collection/item/collection/item
• Collections are Plural
 persons, trees, events
• Standard Terminology
 personId, recordId, collectionId, treeId, UserId
 PID
• Standard Error Responses
12

13. It’s All About Consistency
• Time To Market
• Developer Happiness
• Productivity
13

14. 14
Two roads diverged in a wood and I—
I took the one less traveled by,
And that has made all the difference.
– Robert Frost
REST Client
Proxies

15. REST Standards
REST Standards that bring consistency
15

16. Building the Dog API
(Brian Mulloy inspired)
16

17. Starting Point
• How to Interact with a Dog API
• Often a Method Driven Approach
 When Building the App
 The developer creates a method then discovers…
 He needs an API to complete his method
• Pretty soon you have a mess
• Let’s take a look…
17

18. Dog Service (method-driven approach)
18

19. What’s Wrong with our Dog API?
• Verbs are at the beginning and at the end
 Some have verbs and some don’t
• API is not guiding the developer
• No consistency
• Also, the chances of new hires improving the code are not good – in
fact, the chances of them making it more confusing are very good!
 Why? Again, lack of consistency.
19

20. A Dog’s World Is Big!
20

21. Way Big!
21

22. Dog Service (Expanded)
22

23. This can become a slippery slope, so
Keep the simple things simple
23

24. Keep It Simple
24
Please, something
good happen!

25. 2 Base URLs Per Resource
The first is for a collection:
/dogs
The second is for an element:
/dogs/1234
25

26. HTTP Verbs CRUD
POST Create
GET Read
PUT Update
DELETE Delete
26
Use 4 HTTP Verbs

27. API Design Table
27
Resource
POST
create
GET
read
PUT
update
DELETE
delete
/dogs
Create a
new dog
 {dogId}
/dogs/1234

28. Let’s Have Some Fun!
• Let’s design a Dog REST API
• What’s yours going to look like?
• Let’s go to the board and design it together
 We’ll take 9.571 minutes
 Who will our leader be?
• Questions before we start???
• Go!
28

29. 10 Minutes For API Design

30. 1 Minute Presentations
You’ve Got 1 Minute To Present!
30

31. Let’s Learn More
Now that you’ve designed your own API,
let’s talk design again and we’ll start with URLs
We only need two base URLs per resource.
31

32. Harold’s Dogs API
32
Resource
POST
create
GET
read
PUT
update
DELETE
delete
/dogs
/dogs/{dogId}
Create a
new dog
 {dogId}
Error
List dogs
Get a dog
If not exists
then error
Error Error
Update dog
If not exists
then error
Delete dog
If not exists
then error
* Resist the temptation to use verbs for such things as making your
dog run for example: /dogs/{dogId}/setDogToRunningInPark

33. Good, Bad & Ugly
• Good
• Bad
• Ugly
33
Nouns
Verbs (slippery slope)
/dogs/1234/SetDogToRunningStateInPark
– Instead, update properties using PUT

34. Plurals or Singulars?
• Dog vs Dogs
• Owner vs Owners
• Leash vs Leashes
• Choose one! Consistency please
• Ancestry standard is plurals
34

35. Abstract or concrete naming?
35

36. Abstract to Concrete Continuum
• Super High
• High
• Medium
• Low
/things
/animals
/dogs
/labrador

37. Concrete is better than abstract.
37
/dogs

38. What about associations?
38
GET /owners/5678/dogs
POST /owners/5678/dogs

39. What about complex variations?
39

40. Let’s Hide Complexity
40

41. Hiding the Complexity
41
PUT (update) like this:
PUT /dogs/1234
<Dog>
<Color>Brown</Color>
<Location>yard</Location>
<State>Running</State>
</Dog>

42. Other Stuff
42

43. Versioning Standard
43
• Terracotta Warriors – 1st Emperor of China (210 BCE)
- 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses
- Each face unique
• Required
 Facebook’s Exp
• Major Versions Only
 Rare
 Minor changes OK
- Additive
- Robustness Principle

44. Versioning Standard
44
Versioning Examples:
Github.com
Accept: application/vnd.github.v3+json
Odesk.com
"Accept: application/vnd.odesk.api-v1+json“
FamilySearch.org
“Accept: application/x-fs-v1+json”
Pivotallabs.com
Accept: application/vnd.github[.version].param[+json]
David Zuelke
Accept: application/vnd.com.myservice.v2+xml
• Ancestry Versioning
 External Standard (public facing): place version in url on far left
- /v1/dogs/{dogId}
 Internal Standard
- Accept Header: “accept: application/[component Id].v3+json”

45. Other Standards
45
• Pagination: ?page=1&rows=100
LinkedIn: start + count
Google: (#s are one start based)
+ num (nextpage)
Facebook: offset + limit
Twitter: page + rpp
Spring: page + size
FamilySearch: start + count
FaGceitbHouobk: page + per_page
/joe.smith/friends?fields=id,name,picture
• Counting: /v1/dogs/count
• Casing
 URLs Lowercase (Service-Tier)
“Be liberal in what you accept and conservative in what you send”
 Properties PascalCase (language agnostic)
• Searching: /v1/dogs/search
 POST body
• Partial Response: ?fields=name,description,age
Google
?fields=title,media:group(media:thumbnail)

46. 46
Use 2 base URLs
Use HTTP
verbs – CRUD
Doggone ya,
use Nouns
Oh, and hide the
complexity
REST
Summation

47. Client Proxy Standards
Standards for client proxy
47

48. Single Request & Response
• Use Wrapper Classes
 Helps with versioning
• Naming Standard
 Method name followed by "Request"
or "Response"
• Example
GetDogResponse response =
GetDog(GetDogRequest request);
48

49. 49
Hi, my
name is Dug
public class Dog
{
long DogId,
string Name, “Dug”
string Description,
enum Color
string Owner “Master”
enum ActivityState
bool TailState
etc
}
Request & Response Objects

50. Method Naming
• Use Full Words
• Start with a Verb – End with a Noun
 Use CRUD verbs only:
- Get, Add, Update, Delete
• Use Namespacing to Organize Your API
 Dogs.GetDogs()
 Dogs.AddDog(addDogRequest request)
 Owners.GetDogs()
50

51. Service Naming
• Use Full Words
• Limit Name to 2 Words
 Users
 Trees
 Navigation
 Records
• Bad to Good
OREM Record Corrections
51

52. Proxy Guidelines
• Design interfaces from the client’s perspective
• An API design should make using it very obvious
• Design as a group
 Two heads are usually better than one
• Remember: Good designs take time - and it's worth it!
 Take the time to make good decisions
52

53. Golly, use full
words will ya?
53
Forget yur CRUD verbs
(followed by a noun) and you might
as well forget your can of worms.
Shucks, use
Namespacing!
Yeah, service names ain’t
but one word. Like
Users, Trees, Search, Etc
Proxy
Summation

54. Sum It Up
Let’s review what we’ve talked about
54

55. Let’s Design a Trees API
(your family tree)
55

56. 56
Resource
POST
create
GET
read
PUT
update
DELETE
delete
Let’s Use This Chart Again

57. Let’s Fill In The Chart Together
57

58. Harold’s Trees API
58
Resource
POST
create
GET
read
PUT
update
DELETE
delete
/trees
/trees/{treeId}
Create a
new tree
 {treeId}
Error
List trees
(only those I
own or shared)
Get a tree
If not exists
then error
Error Error
Update tree
If not exists
then error
Delete tree
If not exists
then error
* Resist the temptation to use verbs for such things as making your
tree public for example: /trees/{treeId}/makeMyTreePublic

59. What We Have Learned
• Keep Developer In Mind
• Keep It Simple & Obvious
• Be Consistent
• Design as a Group
• REST APIs
 Use Nouns
 Use HTTP Verbs (CRUD)
 2 URLs per Resource only
 Hide the Complexity
59
• Proxies
– Full words
– CRUD Verbs
▫ Followed by Noun
– Namespaceing
Resource
POST
create
GET
read
PUT
update
DELETE
delete

60. Reputation
Remember, this is Your API.
Your name is on it.
This is your reputation riding on the line.
Will Engineers thank you each day they go to work?
60

61. Thank you
Now Go Design Something Great!