![Page 1: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/1.jpg)
API Design Tour:Digital River
Brian Mulloy
@landlessnessApigee
@apigee
Minnetonka, MN, USA
![Page 2: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/2.jpg)
groups.google.com/group/api-craft
![Page 3: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/3.jpg)
youtube.com/apigee
![Page 4: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/4.jpg)
slideshare.net/apigee
![Page 5: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/5.jpg)
@landlessnessBrian Mulloy
@apigee @DigitalRiverInc
@Rubes_MNEric Roubal
@dougdrivDoug Meisner
![Page 6: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/6.jpg)
What does your company do?
![Page 7: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/7.jpg)
Why do you have an API? How did it get started?
![Page 8: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/8.jpg)
Who are your target developers? Internal? Partners? Open?
![Page 9: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/9.jpg)
How is your API used?
![Page 10: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/10.jpg)
What is your API design philosophy?
![Page 11: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/11.jpg)
Which aspects of the API design have generated the most discussion internally and externally?
![Page 12: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/12.jpg)
How do you approach URI design?
/shoppers/me/categories?expand=category.locale
Content-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”}
Response
This response has been modified from its original version. It has been formatted to fit this slide.
Request
![Page 13: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/13.jpg)
How do you handle multiple formats? What is your default?
accept:application/json
accept:application/xml
XML is default
Header
![Page 14: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/14.jpg)
How do you handle pagination?
/shoppers/me/categories?pageNumber=1&pageSize=10
![Page 15: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/15.jpg)
How do you handle metadata in your responses?
"products":{
"relation":http://developers.digitalriver.com/v1/shoppers/ProductsResourc
e,
"uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600/pr
oducts"
}
<totalResults>43</totalResults>
<totalResultPages>5</totalResultPages>
These responses have been modified from their original version. They have been formatted to fit this slide.
![Page 16: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/16.jpg)
How do you approach HTTP Verbs?
DELETE GET POST
We debated PUT and decided not to use it for the first iteration.
![Page 17: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/17.jpg)
What debate did you have on PUT?
POST /api/dogsfactory to create dog, return 201
POST /api/dogs/fidopartial update, return 201
PUT /api/dogs/fidofido not found, create, 201
fido found, full replace, 204
Factors in PUT vs. POST decision:
• Idempotence
• Factory URLs
• Full Replacement
![Page 18: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/18.jpg)
Which convention do you use for response attribute names?
createdAt
firstName
lastName
![Page 19: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/19.jpg)
How do you handle errors?
400, et al
<?xml version=“1.0” encoding=“UTF-8”?>
<errors>
<error
relation=“http://developers.digitalriver.com/v1/shoppers/ProductsResource”?>
<code>resource-not-found</code>
<description>Product could not be found</description>
</error>
</errors>
![Page 20: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/20.jpg)
How do you handle versions?
/v1/shoppers/me/products/123
![Page 21: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/21.jpg)
How do you handle backwards compatibility, deprecation and obsolescence?
![Page 22: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/22.jpg)
How do you handle search?
/shoppers/me/product-
search?keyword=book&pageSize=5&pageNumber=1
Current search is based off of expressions within keywords.
![Page 23: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/23.jpg)
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‟.
![Page 24: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/24.jpg)
How do you handle long-running or asynchronous requests? Polling?
![Page 25: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/25.jpg)
What design flourishes are you proud of?
![Page 26: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/26.jpg)
What changes have you made to your design because it was confusing for developers?
![Page 27: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/27.jpg)
What are your top level sub domain names for your API and your developer portal?
api.digitalriver.com
developer(s).digitalriver.com
![Page 28: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/28.jpg)
How do you handle authentication and authorization?
Digital River systems are SaaS.
Each client identified by: SiteID, OwnerCompanyID,
ProductOwningCompany, UserID
oAuth token specified by:
Authorization:OAuth oauth_token=xxxx(yes, a bit non-standard)
oAuth token is converted to 4 fields by our API
consolidator layer
Authorization: everyone gets one access level/role
![Page 29: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/29.jpg)
How do you handle SDKs and code libraries?
![Page 30: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/30.jpg)
How have performance considerations impacted your API design?
![Page 31: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/31.jpg)
What challenges can API Teams anticipate as they implement their API initiatives?
![Page 32: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/32.jpg)
What is on your API roadmap?
![Page 33: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/33.jpg)
What else should we know about your API?
![Page 34: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/34.jpg)
Questions from audience?
![Page 35: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/35.jpg)
THANK YOU
Subscribe to API webinars at:
youtube.com/apigee
![Page 36: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/36.jpg)
THANK YOU
Questions and ideas to:
groups.google.com/group/api-craft
![Page 37: API Design Tour with Digital River and Apigee - June 26th, 2012](https://reader033.vdocuments.net/reader033/viewer/2022052623/5598bfbf1a28abd4208b470d/html5/thumbnails/37.jpg)
THANK YOU
Webinar slides at:
slideshare.net/apigee