API Design: An Adoption-Centered Approach

2,434 views

Published on

Application developers are the customers of your API. Success is measured by how quickly those developers enjoy success using your API in their applications. And rapid adoption of an API by your internal, partner, or external developers is all about design.

Building upon their prior work in API design, Marsh Gardiner and Brian Mulloy unveil RV, a style of API design that embraces developer adoption as its guiding principle. They explore the constraints and opportunities introduced by RV and discuss RV's place in the context of other design approaches like REST and Hypermedia.
See the youtube video of this webcast https://www.youtube.com/watch?v=u-bGz9HQIuo

Published in: Software
0 Comments
11 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
2,434
On SlideShare
0
From Embeds
0
Number of Embeds
673
Actions
Shares
0
Downloads
77
Comments
0
Likes
11
Embeds 0
No embeds

No notes for slide
  • URIs are interfaces
    Obviousness
    Every thing gets a resource, an address.

    This is the naming of things. We have a long history of mapping people-friendly names onto machine ids.

    There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
  • So we have things. Things are nouns. Things have a state.

    Now we need to be able to take primitive actions on those things. Things are stored somewhere. Our basic palette of verbs gives us CRUD.

    http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
  • Being pragmatic, let’s spend some time to apply some of them directly.
  • Similar things belong in groups
    Case sensitivity
    Avoid hierarchies

    https://stripe.com/docs/api
  • Consider the developer adoption perspective when wrestling with API design problems.
    Check out resourceverb.com for more background and patterns, and get in touch with us through the channels you find there.
    … and start making better APIs.
  • API Design: An Adoption-Centered Approach

    1. 1. API Design Brian Mulloy @landlessness Marsh Gardiner @earth2marsh An Adoption-Centered Approach
    2. 2. @landlessness Brian Mulloy @earth2marsh Marsh Gardiner
    3. 3. http://iloveapis2014.com
    4. 4. groups.google.com/group/api-craft
    5. 5. youtube.com/apigee
    6. 6. slideshare.net/apigee
    7. 7. Integers as a Service
    8. 8. Overview • How did we get here? • Where are we now? • Where are we going? • How are we going to get there? • Questions
    9. 9. How did we get here?
    10. 10. In the beginning…
    11. 11. SOAP and XML-RPC
    12. 12. REST
    13. 13. The rise of… • Software as a Service • Web Mashups • Virtualization • User Experience • Mobile
    14. 14. Web vs App
    15. 15. Technology unlocks technology…
    16. 16. Gehry vs Winnebago photo: uggb
    17. 17. Where are we now?
    18. 18. Refocusing API design
    19. 19. Passion (and controversy)
    20. 20. API Craft Conference http://api-craft.org Monday, July 28th – Wednesday July 30th
    21. 21. Hypermedia Panel API Craft Conference - http://api-craft.org • Collection+JSON –Mike Amundsen • Hydra –Markus Lanthaler • Mason –Jørn Wildt • HAL –Mike Kelly • JSON API –Steve Klabnik • Siren –Kevin Swiber
    22. 22. Gehry vs Winnebago photo: uggb
    23. 23. Designing for adoption
    24. 24. Resource (a thing that lives somewhere) 26 IP: 173.194.70.102 ➡ google.com Twitter: 14352786 ➡ @earth2marsh https://github.com/apigee
    25. 25. Verb
    26. 26. Applying RV patterns
    27. 27. Collections and entities https://api.stripe.com/ Summary of Resource URL Patterns /v1/charges /v1/charges/{CHARGE_ID} /v1/coupons /v1/coupons/{COUPON_ID} /v1/customers /v1/customers/{CUSTOMER_ID}
    28. 28. Versions /2010-04-01/Accounts/ Twilio /services/data/v29.0/sobjects/Account Salesforce /v2/users Foursquare
    29. 29. Query Parameters /1.1/search/tweets.json?q=%23superbowl &result_type=recent Twitter
    30. 30. Header Parameters
    31. 31. Conveniences /me Facebook /v1/people/~ LinkedIn /v2/checkins/recent Foursquare
    32. 32. Formats /users/3207.json SoundCloud /users/3207
    33. 33. Formats
    34. 34. Actions /search?q=watermelon&type=post Facebook /convert?from=EUR&to=CNY&amount=100 (hypothetical) /droplets/{droplet_id}/reboot DigitalOcean
    35. 35. Authentication
    36. 36. Dates "created_at": "Thu Nov 03 05:19:38 +0000 2011" Twitter "DateTime": "2011-10-29T09:35:00Z" Bing "createdAt": 1320296464 Foursquare
    37. 37. Filters /me?fields=name,birthday,photos.limit(10) .fields(id,picture),videos.type(tagged) .limit(10).fields(id, source) Facebook
    38. 38. offset, limit Facebook page, rpp Twitter start, count LinkedIn Pagination
    39. 39. Pagination offset, limit Facebook
    40. 40. HATEOAS and the Hypermedia Constraint
    41. 41. Hypermedia
    42. 42. Great moments in mishandled error code history
    43. 43. Errors
    44. 44. SDKs
    45. 45. Perfect is the enemy of done
    46. 46. General philosophy
    47. 47. Questions rv@apigee.com, @ResourceVerb brian@apigee.com, @landlessness marsh@apigee.com, @earth2marsh
    48. 48. THANK YOU Brian Mulloy @landlessness Marsh Gardiner @earth2marsh
    49. 49. THANK YOU Subscribe to webcasts at: youtube.com/apigee
    50. 50. THANK YOU Questions and ideas to: groups.google.com/group/api-craft
    51. 51. THANK YOU Webcast slides at: slideshare.net/apigee
    52. 52. THANK YOU Brian Mulloy @landlessness Marsh Gardiner @earth2marsh

    ×