API Design Tour with Digital River and Apigee - June 26th, 2012
Upcoming SlideShare
Loading in...5

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



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

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



Total Views
Views on SlideShare
Embed Views



1 Embed 14

http://www.linkedin.com 14



Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
Post Comment
Edit your comment
  • 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 API Design Tour with Digital River and Apigee - June 26th, 2012 Presentation Transcript

  • API Design Tour:Digital RiverMinnetonka, MN, USABrian Mulloy Apigee@landlessness @apigee
  • groups.google.com/group/api-craft
  • youtube.com/apigee
  • slideshare.net/apigee
  • @apigee @DigitalRiverInc@landlessness @Rubes_MN @dougdriv Brian Mulloy Eric Roubal Doug Meisner
  • What does your company do?
  • Why do you have an API? How did it get started?
  • Who are your target developers? Internal?Partners? Open?
  • How is your API used?
  • What is your API design philosophy?
  • Which aspects of the API design have generatedthe most discussion internally and externally?
  • 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.
  • How do you handle multiple formats? What is yourdefault? Header accept:application/json accept:application/xml XML is default
  • How do you handle pagination?/shoppers/me/categories?pageNumber=1&pageSize=10
  • 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.
  • How do you approach HTTP Verbs? DELETE GET POST We debated PUT and decided not to use it for the first iteration.
  • 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
  • Which convention do you use for responseattribute names? createdAt firstName lastName
  • 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>
  • How do you handle versions?/v1/shoppers/me/products/123
  • How do you handle backwards compatibility,deprecation and obsolescence?
  • How do you handle search?/shoppers/me/product-search?keyword=book&pageSize=5&pageNumber=1 Current search is based off of expressions within keywords.
  • 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‟.
  • How do you handle long-running or asynchronousrequests? Polling?
  • What design flourishes are you proud of?
  • What changes have you made to your designbecause it was confusing for developers?
  • What are your top level sub domain names foryour API and your developer portal? api.digitalriver.com developer(s).digitalriver.com
  • 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
  • How do you handle SDKs and code libraries?
  • How have performance considerations impactedyour API design?
  • What challenges can API Teams anticipate as theyimplement their API initiatives?
  • What is on your API roadmap?
  • What else should we know about your API?
  • Questions from audience?
  • THANK YOUSubscribe to API webinars at:youtube.com/apigee
  • THANK YOUQuestions and ideas to:groups.google.com/group/api-craft
  • THANK YOUWebinar slides at:slideshare.net/apigee
  • THANK YOUContact me at:@landlessnessbrian@apigee.com@apigee