API Design Tour: Digital River

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 backwardscompatibility, 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

http://blog.apigee.com	1614
http://apigee.com	149
http://feeds.apigee.com	67
http://mktg-dev.wearepropeople.md	7
http://blog.sonoasystems.com	7
http://blog-dev.wearepropeople.md	5
http://edit.apigee.net	5
http://webcache.googleusercontent.com	3
http://feeds.feedburner.com	2
http://www.directrss.co.il	1
http://blog-dev.apigee.com	1
http://www.hanrss.com	1
http://ip54.216-86-157.static.steadfast.net	1

API Design Tour: Digital River

by Apigee on Jun 26, 2012

Accessibility

Categories

Upload Details

Usage Rights

13 Embeds 1,863

Statistics

API Design Tour: Digital River Presentation Transcript