1. 1. API Simplicity == Speed Designing APIs That Are Easy and Fun to Use Harold Madsen, Director, Ancestry Positions: CrossCut Engineering + External APIs + Notification Speaker: API Strategy (San Fran), RootsTech (SLC), FamilySearch DevCon (BYU) Publisher: InformationWeek.com + Ancestry TechRoots Blogger February 11, 2015
2. 2. Agenda I. Design Concepts & Principles II. REST Standards III. Sum It Up Frederick Douglass, abolitionist
3. 3. 3 Design Concepts Before we talk API standards, lets cover some concepts
4. 4. Design Affordance How A Physical Item Is Designed Instructs How Its 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 -> lets 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} Service Name: OREM7
8. 8. A Pragmatic Approach to Great APIs 8 - Brian Mulloy RESTful API Design @landlessness Keep the client (developer) in mind Design for simplicity and ease of use Consistent APIs make for happy developers
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. 10 Design Principles What are Ancestrys guiding principles?
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 Avoid method-driven approach11
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. Its All About Consistency Time To Market Developer Happiness Productivity 13
14. 14. REST Standards REST Standards that bring consistency 14
15. 15. Building the Dog API (Brian Mulloy inspired) 15
16. 16. 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 Lets take a look 16
17. 17. Dog Service (method-driven approach) 17
18. 18. Whats Wrong with our Dog API? Verbs are at the beginning and at the end Some have verbs and some dont 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. 18
19. 19. A Dogs World Is Big! 19
20. 20. Way Big! 20
21. 21. Dog Service (Expanded) 21
22. 22. This can become a slippery slope, so Keep the simple things simple 22
23. 23. Keep It Simple 23 Please, something good happen!
24. 24. 2 Base URLs Per Resource The first is for a collection: /dogs The second is for an element: /dogs/1234 24
25. 25. HTTP Verbs CRUD POST Create GET Read PUT Update DELETE Delete 25 Use 4 HTTP Verbs
26. 26. API Design Table 26 Resource POST create GET read PUT update DELETE delete /dogs Create a new dog {dogId} /dogs/1234
27. 27. Lets Fill In The Chart Together 27
28. 28. Harolds Dogs API 28 Resource POST create GET read PUT update DELETE delete * Resist the temptation to use verbs for such things as making your dog run for example: /dogs/{dogId}/setDogToRunningInPark /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
29. 29. Good, Bad & Ugly Good Bad Ugly 29 Nouns Verbs (slippery slope) /dogs/1234/SetDogToRunningStateInPark Instead, update properties using PUT
30. 30. Abstract or concrete naming? 30
31. 31. Abstract to Concrete Continuum Super High High Medium Low /things /animals /dogs /labrador
32. 32. Concrete is better than abstract. 32 /dogs
33. 33. 33 PUT (update) like this: PUT /dogs/{dogId} BrownyardRunning Hiding the Complexity
34. 34. 34 Resource POST create GET read PUT update DELETE delete Lets Use This Chart Again
35. 35. Lets Fill In A Family Tree API Together 35
36. 36. Harolds Trees API 36 Resource POST create GET read PUT update DELETE delete * Resist the temptation to use verbs for such things as making your tree public for example: /trees/{treeId}/makeMyTreePublic /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
37. 37. 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? 37
38. 38. Thank you Now Go Design Something Great!