Digital River is a commerce platform that provides an API for developers to access its e-commerce functionality. Some key points from the discussion: - The API was created to allow partners and customers to integrate with Digital River's systems like shopping carts and product catalogs. - URI design, error handling, authentication, and asynchronous requests were some of the most discussed design aspects both internally and with developers. - The API uses conventions like RESTful design with HTTP verbs, JSON responses with pagination and metadata, and versioning in the URL to make it intuitive for developers.

1. API Design Tour:
Digital River
Minnetonka, MN, USA
Brian Mulloy Apigee
@landlessness @apigee

2. groups.google.com/group/api-craft

3. youtube.com/apigee

4. slideshare.net/apigee

5. @apigee @DigitalRiverInc
@landlessness @Rubes_MN @dougdriv
Brian Mulloy Eric Roubal Doug Meisner

6. What does your company do?

7. Why do you have an API? How did it get started?

8. Who are your target developers? Internal?
Partners? Open?

9. How is your API used?

10. What is your API design philosophy?

11. Which aspects of the API design have generated
the most discussion internally and externally?

12. How do you approach URI design?
Request
/shoppers/me/categories?expand=category.locale
Response
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”}
This response has been modified from its original version. It has been formatted to fit this slide.

13. How do you handle multiple formats? What is your
default?
Header
accept:application/json
accept:application/xml
XML is default

14. How do you handle pagination?
/shoppers/me/categories?pageNumber=1&pageSize=10

15. How do you handle metadata in your responses?
<totalResults>43</totalResults>
<totalResultPages>5</totalResultPages>
"products":{
"relation":http://developers.digitalriver.com/v1/shoppers/ProductsResourc
e,
"uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600/pr
oducts"
}
These responses have been modified from their original version. They have been formatted to fit this slide.

16. How do you approach HTTP Verbs?
DELETE GET POST
We debated PUT and decided not to use it for the first iteration.

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. Which convention do you use for response
attribute names?
createdAt
firstName
lastName

19. 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>

20. How do you handle versions?
/v1/shoppers/me/products/123

21. How do you handle backwards
compatibility, deprecation and obsolescence?

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. 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. How do you handle long-running or asynchronous
requests? Polling?

25. What design flourishes are you proud of?

26. What changes have you made to your design
because it was confusing for developers?

27. What are your top level sub domain names for
your API and your developer portal?
api.digitalriver.com
developer(s).digitalriver.com

28. How do you handle authentication and
authorization?
Digital River systems are SaaS.
Each client identified by:
SiteID, OwnerCompanyID, ProductOwningCompany, User
ID
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

29. How do you handle SDKs and code libraries?

30. How have performance considerations impacted
your API design?

31. What challenges can API Teams anticipate as they
implement their API initiatives?

32. What is on your API roadmap?

33. What else should we know about your API?

34. Questions from audience?

35. THANK YOU
Subscribe to API webinars at:
youtube.com/apigee

36. THANK YOU
Questions and ideas to:
groups.google.com/group/api-craft

37. THANK YOU
Webinar slides at:
slideshare.net/apigee

38. THANK YOU
Contact me at:
@landlessness
brian@apigee.com
@apigee