Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
API Simplicity == Speed 
Designing APIs That Are Easy and Fun to Use 
Harold Madsen, API Director @ Ancestry.com 
Position...
Agenda 
I. Design Concepts 
II. Design Principles 
III. REST Standards 
IV. Client Proxy Standards 
V. Sum It Up 
Frederic...
3 
Design Concepts 
Before we talk API standards, let’s cover some concepts
Design Affordance 
How A Physical Item 
Is Designed 
Instructs 
How It’s Used 
Psychologist James J. Gibson originally int...
Design Matters 
www.baddesigns.com 
5
Design Matters for APIs Too 
• Good, Bad and the Ugly 
• Used a Bad API? What is it like going to work each day? 
6 
Addre...
API Smell Test 
• Does It Pass the Smell Test? 
• Methods 
 tSndMl 
 MyEventType -> let’s use verbs 
• Parameters 
 Sen...
A Pragmatic Approach to Great APIs 
8 
- Brian Mulloy 
make for happy developers 
“RESTful API Design” 
@landlessness 
Con...
Programs must be written 
for people to read, and 
only incidentally for 
machines to execute 
9 
“ 
- Abelson & Sussman 
...
Design Principles 
What are Ancestry.com’s guiding principles? 
10
Design Guidelines 
• Design with Developer in Mind 
• Be Consistent 
 help developers “guess the answer” 
• Your API shou...
Consistency 
Help Developers Anticipate Your Thinking 
• Standard URL Patterns 
 collection/item/collection/item 
• Colle...
It’s All About Consistency 
• Time To Market 
• Developer Happiness 
• Productivity 
13
14 
Two roads diverged in a wood and I— 
I took the one less traveled by, 
And that has made all the difference. 
– Robert...
REST Standards 
REST Standards that bring consistency 
15
Building the Dog API 
(Brian Mulloy inspired) 
16
Starting Point 
• How to Interact with a Dog API 
• Often a Method Driven Approach 
 When Building the App 
 The develop...
Dog Service (method-driven approach) 
18
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 no...
A Dog’s World Is Big! 
20
Way Big! 
21
Dog Service (Expanded) 
22
This can become a slippery slope, so 
Keep the simple things simple 
23
Keep It Simple 
24 
Please, something 
good happen!
2 Base URLs Per Resource 
The first is for a collection: 
/dogs 
The second is for an element: 
/dogs/1234 
25
HTTP Verbs CRUD 
POST Create 
GET Read 
PUT Update 
DELETE Delete 
26 
Use 4 HTTP Verbs
API Design Table 
27 
Resource 
POST 
create 
GET 
read 
PUT 
update 
DELETE 
delete 
/dogs 
Create a 
new dog 
 {dogId} ...
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 desig...
10 Minutes For API Design
1 Minute Presentations 
You’ve Got 1 Minute To Present! 
30
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 ...
Harold’s Dogs API 
32 
Resource 
POST 
create 
GET 
read 
PUT 
update 
DELETE 
delete 
/dogs 
/dogs/{dogId} 
Create a 
new...
Good, Bad & Ugly 
• Good 
• Bad 
• Ugly 
33 
Nouns 
Verbs (slippery slope) 
/dogs/1234/SetDogToRunningStateInPark 
– Inste...
Plurals or Singulars? 
• Dog vs Dogs 
• Owner vs Owners 
• Leash vs Leashes 
• Choose one! Consistency please 
• Ancestry ...
Abstract or concrete naming? 
35
Abstract to Concrete Continuum 
• Super High 
• High 
• Medium 
• Low 
/things 
/animals 
/dogs 
/labrador
Concrete is better than abstract. 
37 
/dogs
What about associations? 
38 
GET /owners/5678/dogs 
POST /owners/5678/dogs
What about complex variations? 
39
Let’s Hide Complexity 
40
Hiding the Complexity 
41 
PUT (update) like this: 
PUT /dogs/1234 
<Dog> 
<Color>Brown</Color> 
<Location>yard</Location>...
Other Stuff 
42
Versioning Standard 
43 
• Terracotta Warriors – 1st Emperor of China (210 BCE) 
- 8,000 soldiers, 130 chariots with 520 h...
Versioning Standard 
44 
Versioning Examples: 
Github.com 
Accept: application/vnd.github.v3+json 
Odesk.com 
"Accept: app...
Other Standards 
45 
• Pagination: ?page=1&rows=100 
LinkedIn: start + count 
Google: (#s are one start based) 
+ num (nex...
46 
Use 2 base URLs 
Use HTTP 
verbs – CRUD 
Doggone ya, 
use Nouns 
Oh, and hide the 
complexity 
REST 
Summation
Client Proxy Standards 
Standards for client proxy 
47
Single Request & Response 
• Use Wrapper Classes 
 Helps with versioning 
• Naming Standard 
 Method name followed by "R...
49 
Hi, my 
name is Dug 
public class Dog 
{ 
long DogId, 
string Name, “Dug” 
string Description, 
enum Color 
string Own...
Method Naming 
• Use Full Words 
• Start with a Verb – End with a Noun 
 Use CRUD verbs only: 
- Get, Add, Update, Delete...
Service Naming 
• Use Full Words 
• Limit Name to 2 Words 
 Users 
 Trees 
 Navigation 
 Records 
• Bad to Good 
OREM ...
Proxy Guidelines 
• Design interfaces from the client’s perspective 
• An API design should make using it very obvious 
• ...
Golly, use full 
words will ya? 
53 
Forget yur CRUD verbs 
(followed by a noun) and you might 
as well forget your can of...
Sum It Up 
Let’s review what we’ve talked about 
54
Let’s Design a Trees API 
(your family tree) 
55
56 
Resource 
POST 
create 
GET 
read 
PUT 
update 
DELETE 
delete 
Let’s Use This Chart Again
Let’s Fill In The Chart Together 
57
Harold’s Trees API 
58 
Resource 
POST 
create 
GET 
read 
PUT 
update 
DELETE 
delete 
/trees 
/trees/{treeId} 
Create a ...
What We Have Learned 
• Keep Developer In Mind 
• Keep It Simple & Obvious 
• Be Consistent 
• Design as a Group 
• REST A...
Reputation 
Remember, this is Your API. 
Your name is on it. 
This is your reputation riding on the line. 
Will Engineers ...
Thank you 
Now Go Design Something Great!
Upcoming SlideShare
Loading in …5
×

API Simplicity == Speed; Designing APIs That are Easy and Fun to Use

540 views

Published on

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

Published in: Technology
  • Be the first to comment

API Simplicity == Speed; Designing APIs That are Easy and Fun to Use

  1. 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. 2. Agenda I. Design Concepts II. Design Principles III. REST Standards IV. Client Proxy Standards V. Sum It Up Frederick Douglass, abolitionist
  3. 3. 3 Design Concepts Before we talk API standards, let’s cover some concepts
  4. 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. 5. Design Matters www.baddesigns.com 5
  6. 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. 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. 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. 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. 10. Design Principles What are Ancestry.com’s guiding principles? 10
  11. 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. 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. 13. It’s All About Consistency • Time To Market • Developer Happiness • Productivity 13
  14. 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. 15. REST Standards REST Standards that bring consistency 15
  16. 16. Building the Dog API (Brian Mulloy inspired) 16
  17. 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. 18. Dog Service (method-driven approach) 18
  19. 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. 20. A Dog’s World Is Big! 20
  21. 21. Way Big! 21
  22. 22. Dog Service (Expanded) 22
  23. 23. This can become a slippery slope, so Keep the simple things simple 23
  24. 24. Keep It Simple 24 Please, something good happen!
  25. 25. 2 Base URLs Per Resource The first is for a collection: /dogs The second is for an element: /dogs/1234 25
  26. 26. HTTP Verbs CRUD POST Create GET Read PUT Update DELETE Delete 26 Use 4 HTTP Verbs
  27. 27. API Design Table 27 Resource POST create GET read PUT update DELETE delete /dogs Create a new dog  {dogId} /dogs/1234
  28. 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. 29. 10 Minutes For API Design
  30. 30. 1 Minute Presentations You’ve Got 1 Minute To Present! 30
  31. 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. 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. 33. Good, Bad & Ugly • Good • Bad • Ugly 33 Nouns Verbs (slippery slope) /dogs/1234/SetDogToRunningStateInPark – Instead, update properties using PUT
  34. 34. Plurals or Singulars? • Dog vs Dogs • Owner vs Owners • Leash vs Leashes • Choose one! Consistency please • Ancestry standard is plurals 34
  35. 35. Abstract or concrete naming? 35
  36. 36. Abstract to Concrete Continuum • Super High • High • Medium • Low /things /animals /dogs /labrador
  37. 37. Concrete is better than abstract. 37 /dogs
  38. 38. What about associations? 38 GET /owners/5678/dogs POST /owners/5678/dogs
  39. 39. What about complex variations? 39
  40. 40. Let’s Hide Complexity 40
  41. 41. Hiding the Complexity 41 PUT (update) like this: PUT /dogs/1234 <Dog> <Color>Brown</Color> <Location>yard</Location> <State>Running</State> </Dog>
  42. 42. Other Stuff 42
  43. 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. 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. 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. 46 Use 2 base URLs Use HTTP verbs – CRUD Doggone ya, use Nouns Oh, and hide the complexity REST Summation
  47. 47. Client Proxy Standards Standards for client proxy 47
  48. 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. 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. 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. 51. Service Naming • Use Full Words • Limit Name to 2 Words  Users  Trees  Navigation  Records • Bad to Good OREM Record Corrections 51
  52. 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. 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. 54. Sum It Up Let’s review what we’ve talked about 54
  55. 55. Let’s Design a Trees API (your family tree) 55
  56. 56. 56 Resource POST create GET read PUT update DELETE delete Let’s Use This Chart Again
  57. 57. Let’s Fill In The Chart Together 57
  58. 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. 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. 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. 61. Thank you Now Go Design Something Great!

×