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?
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
