API Simplicity == Speed; Designing APIs That are Easy and Fun to Use
•Download as PPTX, PDF•
2 likes•824 views
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
Report
Share
API Simplicity == Speed; Designing APIs That are Easy and Fun to Use
- 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
- 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!