1. API Simplicity == SpeedDesigning APIs That Are Easy and Fun to UseHarold Madsen, API Director @ Ancestry.comPositions: Platform Initiative + External APIs + Notification + CommunitySpeaker: API Strategy (San Fran), RootsTech (SLC), FamilySearch DevCon (BYU)Publisher: InformationWeek.comSeptember 18, 2014

2. AgendaI. Design ConceptsII. Design PrinciplesIII. REST StandardsIV. Client Proxy StandardsV. Sum It UpFrederick Douglass, abolitionist 3. 3Design ConceptsBefore we talk API standards, lets cover some concepts 4. Design AffordanceHow A Physical ItemIs DesignedInstructsHow Its UsedPsychologist James J. Gibson originally introduced the term in his1977 article "The Theory of Affordances and explored it more fullyin his book The Ecological Approach to Visual Perception in 19794 5. Design Matterswww.baddesigns.com5 6. Design Matters for APIs Too Good, Bad and the Ugly Used a Bad API? What is it like going to work each day?6AddressVerifyCallbackDoCaptureDoVoidMassPaymentGetBalanceTransactionSearchUpdateRecurringPaymentProfileSetExpressCheckOutRefundTransactionEtc.account.GetBalance()payments.GetInvoice()payments.Void(invoiceId)payments.Search()Etc. 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}7 Service Name: OREM 8. A Pragmatic Approach to Great APIs8- Brian Mulloymake for happy developersRESTful API Design@landlessnessConsistent APIsDesign for simplicityand ease of useKeep the client (developer)in mind 9. Programs must be writtenfor people to read, andonly incidentally formachines to execute9- Abelson & SussmanStructure & InterpretationOf Computer Programs 10. Design PrinciplesWhat are Ancestry.coms 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 decisions11 Avoid method-driven approach 12. ConsistencyHelp 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 Responses12 13. Its All About Consistency Time To Market Developer Happiness Productivity13 14. 14Two roads diverged in a wood and II took the one less traveled by,And that has made all the difference. Robert FrostREST ClientProxies 15. REST StandardsREST Standards that bring consistency15 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 Lets take a look17 18. Dog Service (method-driven approach)18 19. 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 infact, the chances of them making it more confusing are very good! Why? Again, lack of consistency.19 20. A Dogs World Is Big!20 21. Way Big!21 22. Dog Service (Expanded)22 23. This can become a slippery slope, soKeep the simple things simple23 24. Keep It Simple24Please, somethinggood happen! 25. 2 Base URLs Per ResourceThe first is for a collection:/dogsThe second is for an element:/dogs/123425 26. HTTP Verbs CRUDPOST CreateGET ReadPUT UpdateDELETE Delete26Use 4 HTTP Verbs 27. API Design Table27ResourcePOSTcreateGETreadPUTupdateDELETEdelete/dogsCreate anew dog {dogId}/dogs/1234 28. Lets Have Some Fun! Lets design a Dog REST API Whats yours going to look like? Lets go to the board and design it together Well take 9.571 minutes Who will our leader be? Questions before we start??? Go!28 29. 10 Minutes For API Design 30. 1 Minute PresentationsYouve Got 1 Minute To Present!30 31. Lets Learn MoreNow that youve designed your own API,lets talk design again and well start with URLsWe only need two base URLs per resource.31 32. Harolds Dogs API32ResourcePOSTcreateGETreadPUTupdateDELETEdelete/dogs/dogs/{dogId}Create anew dog {dogId}ErrorList dogsGet a dogIf not existsthen errorError ErrorUpdate dogIf not existsthen errorDelete dogIf not existsthen error* Resist the temptation to use verbs for such things as making yourdog run for example: /dogs/{dogId}/setDogToRunningInPark 33. Good, Bad & Ugly Good Bad Ugly33NounsVerbs (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 plurals34 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?38GET /owners/5678/dogsPOST /owners/5678/dogs 39. What about complex variations?39 40. Lets Hide Complexity40 41. Hiding the Complexity41PUT (update) like this:PUT /dogs/1234BrownyardRunning 42. Other Stuff42 43. Versioning Standard43 Terracotta Warriors 1st Emperor of China (210 BCE)- 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses- Each face unique Required Facebooks Exp Major Versions Only Rare Minor changes OK- Additive- Robustness Principle 44. Versioning Standard44Versioning Examples:Github.comAccept: application/vnd.github.v3+jsonOdesk.com"Accept: application/vnd.odesk.api-v1+jsonFamilySearch.orgAccept: application/x-fs-v1+jsonPivotallabs.comAccept: application/vnd.github[.version].param[+json]David ZuelkeAccept: 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 Standards45 Pagination: ?page=1&rows=100LinkedIn: start + countGoogle: (#s are one start based)+ num (nextpage)Facebook: offset + limitTwitter: page + rppSpring: page + sizeFamilySearch: start + countFaGceitbHouobk: 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,ageGoogle?fields=title,media:group(media:thumbnail) 46. 46Use 2 base URLsUse HTTPverbs CRUDDoggone ya,use NounsOh, and hide thecomplexityRESTSummation 47. Client Proxy StandardsStandards for client proxy47 48. Single Request & Response Use Wrapper Classes Helps with versioning Naming Standard Method name followed by "Request"or "Response" ExampleGetDogResponse response =GetDog(GetDogRequest request);48 49. 49Hi, myname is Dugpublic class Dog{long DogId,string Name, Dugstring Description,enum Colorstring Owner Masterenum ActivityStatebool TailStateetc}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 GoodOREM Record Corrections51 52. Proxy Guidelines Design interfaces from the clients 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 decisions52 53. Golly, use fullwords will ya?53Forget yur CRUD verbs(followed by a noun) and you mightas well forget your can of worms.Shucks, useNamespacing!Yeah, service names aintbut one word. LikeUsers, Trees, Search, EtcProxySummation 54. Sum It UpLets review what weve talked about54 55. Lets Design a Trees API(your family tree)55 56. 56ResourcePOSTcreateGETreadPUTupdateDELETEdeleteLets Use This Chart Again 57. Lets Fill In The Chart Together57 58. Harolds Trees API58ResourcePOSTcreateGETreadPUTupdateDELETEdelete/trees/trees/{treeId}Create anew tree {treeId}ErrorList trees(only those Iown or shared)Get a treeIf not existsthen errorError ErrorUpdate treeIf not existsthen errorDelete treeIf not existsthen error* Resist the temptation to use verbs for such things as making yourtree 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 Complexity59 Proxies Full words CRUD Verbs Followed by Noun NamespaceingResourcePOSTcreateGETreadPUTupdateDELETEdelete 60. ReputationRemember, 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 youNow Go Design Something Great!