API Design Tour: Digital River Brian Mulloy @landlessness Apigee @apigee Minnetonka, MN, USA
API Design Tour:Digital River
Brian Mulloy
@landlessnessApigee
@apigee
Minnetonka, MN, USA
groups.google.com/group/api-craft
youtube.com/apigee
slideshare.net/apigee
@landlessnessBrian Mulloy
@apigee @DigitalRiverInc
@Rubes_MNEric Roubal
@dougdrivDoug 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 generated the most discussion internally and externally?
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
How do you handle multiple formats? What is your default?
accept:application/json
accept:application/xml
XML is default
Header
How do you handle pagination?
/shoppers/me/categories?pageNumber=1&pageSize=10
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.
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?
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
Which convention do you use for response attribute names?
createdAt
firstName
lastName
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>
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 asynchronous requests? Polling?
What design flourishes are you proud of?
What changes have you made to your design because it was confusing for developers?
What are your top level sub domain names for your API and your developer portal?
api.digitalriver.com
developer(s).digitalriver.com
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
How do you handle SDKs and code libraries?
How have performance considerations impacted your API design?
What challenges can API Teams anticipate as they implement their API initiatives?
What is on your API roadmap?
What else should we know about your API?
Questions from audience?
THANK YOU
Subscribe to API webinars at:
youtube.com/apigee
THANK YOU
Questions and ideas to:
groups.google.com/group/api-craft
THANK YOU
Webinar slides at:
slideshare.net/apigee