API Simplicity + Consistency == Speed: Designing APIs That Are Easy and Fun to Use
Preview:
Citation preview
- 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. Agenda I. Design Concepts & Principles II. REST
Standards III. Sum It Up Frederick Douglass, abolitionist
- 3. 3 Design Concepts Before we talk API standards, lets cover
some concepts
- 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. 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 -> 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. 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. 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 Ancestrys guiding
principles?
- 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. 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. Its All About Consistency Time To Market Developer
Happiness Productivity 13
- 14. REST Standards REST Standards that bring consistency
14
- 15. Building the Dog API (Brian Mulloy inspired) 15
- 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. Dog Service (method-driven approach) 17
- 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. A Dogs World Is Big! 19
- 20. Way Big! 20
- 21. Dog Service (Expanded) 21
- 22. This can become a slippery slope, so Keep the simple things
simple 22
- 23. Keep It Simple 23 Please, something good happen!
- 24. 2 Base URLs Per Resource The first is for a collection:
/dogs The second is for an element: /dogs/1234 24
- 25. HTTP Verbs CRUD POST Create GET Read PUT Update DELETE
Delete 25 Use 4 HTTP Verbs
- 26. API Design Table 26 Resource POST create GET read PUT
update DELETE delete /dogs Create a new dog {dogId} /dogs/1234
- 27. Lets Fill In The Chart Together 27
- 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. Good, Bad & Ugly Good Bad Ugly 29 Nouns Verbs (slippery
slope) /dogs/1234/SetDogToRunningStateInPark Instead, update
properties using PUT
- 30. Abstract or concrete naming? 30
- 31. Abstract to Concrete Continuum Super High High Medium Low
/things /animals /dogs /labrador
- 32. Concrete is better than abstract. 32 /dogs
- 33. 33 PUT (update) like this: PUT /dogs/{dogId}
BrownyardRunning Hiding the Complexity
- 34. 34 Resource POST create GET read PUT update DELETE delete
Lets Use This Chart Again
- 35. Lets Fill In A Family Tree API Together 35
- 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. 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. Thank you Now Go Design Something Great!