API Design Tour with Digital River and Apigee - June 26th, 2012


Published on

Slides from a Webinar innovator series with Apigee describing Digital River\'s new REST based APIs.

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Creative Commons Attribution-Share Alike 3.0 United States License
  • All long running requests are considered asynchronous and will be setup by an inbound call to be scheduled.So far, no polling
  • No SDKs yet. Reference architecture is almost complete.
  • API Design Tour with Digital River and Apigee - June 26th, 2012

    1. 1. API Design Tour:Digital RiverMinnetonka, MN, USABrian Mulloy Apigee@landlessness @apigee
    2. 2. groups.google.com/group/api-craft
    3. 3. youtube.com/apigee
    4. 4. slideshare.net/apigee
    5. 5. @apigee @DigitalRiverInc@landlessness @Rubes_MN @dougdriv Brian Mulloy Eric Roubal Doug Meisner
    6. 6. What does your company do?
    7. 7. Why do you have an API? How did it get started?
    8. 8. Who are your target developers? Internal?Partners? Open?
    9. 9. How is your API used?
    10. 10. What is your API design philosophy?
    11. 11. Which aspects of the API design have generatedthe most discussion internally and externally?
    12. 12. How do you approach URI design?Request/shoppers/me/categories?expand=category.localeResponseContent-Type:application/json;{"categories":{ "relation":"http://developers.digitalriver.com/v1/shoppers/CategoriesResource", "uri":"https://api.digitalriver.com/v1/shoppers/me/categories", "category":[ { "relation":"http://developers.digitalriver.com/v1/shoppers/CategoriesResource", "uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600", "locale":"en_US", "displayName":"All Products”, "products":{ "relation":"http://developers.digitalriver.com/v1/shoppers/ProductsResource", "uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600/products”} This response has been modified from its original version. It has been formatted to fit this slide.
    13. 13. How do you handle multiple formats? What is yourdefault? Header accept:application/json accept:application/xml XML is default
    14. 14. How do you handle pagination?/shoppers/me/categories?pageNumber=1&pageSize=10
    15. 15. How do you handle metadata in your responses?<totalResults>43</totalResults><totalResultPages>5</totalResultPages>"products":{"relation":http://developers.digitalriver.com/v1/shoppers/ProductsResource,"uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600/products"} These responses have been modified from their original version. They have been formatted to fit this slide.
    16. 16. How do you approach HTTP Verbs? DELETE GET POST We debated PUT and decided not to use it for the first iteration.
    17. 17. What debate did you have on PUT? Factors in PUT vs. POST decision: • Idempotence • Factory URLs • Full Replacement POST /api/dogs factory to create dog, return 201 POST /api/dogs/fido partial update, return 201 PUT /api/dogs/fido fido not found, create, 201 fido found, full replace, 204
    18. 18. Which convention do you use for responseattribute names? createdAt firstName lastName
    19. 19. How do you handle errors?400, et al<?xml version=“1.0” encoding=“UTF-8”?><errors> <errorrelation=“http://developers.digitalriver.com/v1/shoppers/ProductsResource”?> <code>resource-not-found</code> <description>Product could not be found</description> </error></errors>
    20. 20. How do you handle versions?/v1/shoppers/me/products/123
    21. 21. How do you handle backwards compatibility,deprecation and obsolescence?
    22. 22. How do you handle search?/shoppers/me/product-search?keyword=book&pageSize=5&pageNumber=1 Current search is based off of expressions within keywords.
    23. 23. How did you approach procedural style requests?Why did you need them?POST /shoppers/me/carts/active/submit-cart Highly contextual based on oAuth token „shoppers/me‟, „carts/active‟.
    24. 24. How do you handle long-running or asynchronousrequests? Polling?
    25. 25. What design flourishes are you proud of?
    26. 26. What changes have you made to your designbecause it was confusing for developers?
    27. 27. What are your top level sub domain names foryour API and your developer portal? api.digitalriver.com developer(s).digitalriver.com
    28. 28. How do you handle authentication andauthorization?Digital River systems are SaaS.Each client identified by: SiteID, OwnerCompanyID,ProductOwningCompany, UserIDoAuth token specified by:Authorization:OAuth oauth_token=xxxx(yes, a bit non-standard)oAuth token is converted to 4 fields by our APIconsolidator layerAuthorization: everyone gets one access level/role
    29. 29. How do you handle SDKs and code libraries?
    30. 30. How have performance considerations impactedyour API design?
    31. 31. What challenges can API Teams anticipate as theyimplement their API initiatives?
    32. 32. What is on your API roadmap?
    33. 33. What else should we know about your API?
    34. 34. Questions from audience?
    35. 35. THANK YOUSubscribe to API webinars at:youtube.com/apigee
    36. 36. THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
    37. 37. THANK YOUWebinar slides at:slideshare.net/apigee
    38. 38. THANK YOUContact me at:@landlessnessbrian@apigee.com@apigee