SlideShare a Scribd company logo
1 of 38
Download to read offline
API Design Tour:
Digital River
Minnetonka, MN, USA




Brian 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 generated
the most discussion internally and externally?
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.
How do you handle multiple formats? What is your
default?


     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/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.
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 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
THANK YOU
Contact me at:

@landlessness

brian@apigee.com

@apigee

More Related Content

Similar to API Design Tour with Digital River and Apigee - June 26th, 2012

API Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraAPI Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraCA API Management
 
API Discovery: Visibility, Usability, and Advocacy
API Discovery: Visibility, Usability, and AdvocacyAPI Discovery: Visibility, Usability, and Advocacy
API Discovery: Visibility, Usability, and AdvocacyBill Doerrfeld
 
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...CA API Management
 
WSO2Con Asia 2014 - Building the API-Centric Enterprise
WSO2Con Asia 2014 - Building the API-Centric EnterpriseWSO2Con Asia 2014 - Building the API-Centric Enterprise
WSO2Con Asia 2014 - Building the API-Centric EnterpriseWSO2
 
[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DX[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DXKathleen De Roo
 
Data Driven Design: Using Web Analytics to Improve Information Architectures
Data Driven Design: Using Web Analytics to Improve Information ArchitecturesData Driven Design: Using Web Analytics to Improve Information Architectures
Data Driven Design: Using Web Analytics to Improve Information ArchitecturesAndrea Wiggins
 
API Marketing: First Comes Usability, Then Discoverability
API Marketing: First Comes Usability, Then DiscoverabilityAPI Marketing: First Comes Usability, Then Discoverability
API Marketing: First Comes Usability, Then DiscoverabilityBill Doerrfeld
 
LF_APIStrat17_API Marketing: First Comes Usability, then Discoverability
LF_APIStrat17_API Marketing: First Comes Usability, then DiscoverabilityLF_APIStrat17_API Marketing: First Comes Usability, then Discoverability
LF_APIStrat17_API Marketing: First Comes Usability, then DiscoverabilityLF_APIStrat
 
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...apidays
 
Confessions of-a-gadget-holic
Confessions of-a-gadget-holicConfessions of-a-gadget-holic
Confessions of-a-gadget-holicTyrell Perera
 
Architect's Guide to Building an API Program
Architect's Guide to Building an API ProgramArchitect's Guide to Building an API Program
Architect's Guide to Building an API Programclatimer
 
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015Codemotion
 
Real World API Business Models That Worked
Real World API Business Models That WorkedReal World API Business Models That Worked
Real World API Business Models That WorkedProgrammableWeb
 
Applying Domain-Driven Design to APIs and Microservices - Austin API Meetup
Applying Domain-Driven Design to APIs and Microservices  - Austin API MeetupApplying Domain-Driven Design to APIs and Microservices  - Austin API Meetup
Applying Domain-Driven Design to APIs and Microservices - Austin API MeetupLaunchAny
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product StrategyRavi Kumar
 

Similar to API Design Tour with Digital River and Apigee - June 26th, 2012 (20)

API Design Tour: Dell
API Design Tour: DellAPI Design Tour: Dell
API Design Tour: Dell
 
API Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie MitraAPI Introduction - API Management Workshop Munich from Ronnie Mitra
API Introduction - API Management Workshop Munich from Ronnie Mitra
 
What Makes a Great Open API?
What Makes a Great Open API?What Makes a Great Open API?
What Makes a Great Open API?
 
API Discovery: Visibility, Usability, and Advocacy
API Discovery: Visibility, Usability, and AdvocacyAPI Discovery: Visibility, Usability, and Advocacy
API Discovery: Visibility, Usability, and Advocacy
 
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...
Considerations For an API Strategy - Ronnie MItra API Architect Layer 7 Londo...
 
WSO2Con Asia 2014 - Building the API-Centric Enterprise
WSO2Con Asia 2014 - Building the API-Centric EnterpriseWSO2Con Asia 2014 - Building the API-Centric Enterprise
WSO2Con Asia 2014 - Building the API-Centric Enterprise
 
Smartone v1.0
Smartone v1.0Smartone v1.0
Smartone v1.0
 
[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DX[API the Docs Paris 2018] Architecting DX
[API the Docs Paris 2018] Architecting DX
 
Data Driven Design: Using Web Analytics to Improve Information Architectures
Data Driven Design: Using Web Analytics to Improve Information ArchitecturesData Driven Design: Using Web Analytics to Improve Information Architectures
Data Driven Design: Using Web Analytics to Improve Information Architectures
 
API Marketing: First Comes Usability, Then Discoverability
API Marketing: First Comes Usability, Then DiscoverabilityAPI Marketing: First Comes Usability, Then Discoverability
API Marketing: First Comes Usability, Then Discoverability
 
LF_APIStrat17_API Marketing: First Comes Usability, then Discoverability
LF_APIStrat17_API Marketing: First Comes Usability, then DiscoverabilityLF_APIStrat17_API Marketing: First Comes Usability, then Discoverability
LF_APIStrat17_API Marketing: First Comes Usability, then Discoverability
 
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...
INTERFACE by apidays 2023 - APIs with bounded contexts, Jose Haro Peralta, mi...
 
Confessions of-a-gadget-holic
Confessions of-a-gadget-holicConfessions of-a-gadget-holic
Confessions of-a-gadget-holic
 
Architect's Guide to Building an API Program
Architect's Guide to Building an API ProgramArchitect's Guide to Building an API Program
Architect's Guide to Building an API Program
 
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015
Building Successful APIs Overnight - Orlando K - Codemotion Rome 2015
 
29.4 mb
29.4 mb29.4 mb
29.4 mb
 
29.4 Mb
29.4 Mb29.4 Mb
29.4 Mb
 
Real World API Business Models That Worked
Real World API Business Models That WorkedReal World API Business Models That Worked
Real World API Business Models That Worked
 
Applying Domain-Driven Design to APIs and Microservices - Austin API Meetup
Applying Domain-Driven Design to APIs and Microservices  - Austin API MeetupApplying Domain-Driven Design to APIs and Microservices  - Austin API Meetup
Applying Domain-Driven Design to APIs and Microservices - Austin API Meetup
 
APIs as a Product Strategy
APIs as a Product StrategyAPIs as a Product Strategy
APIs as a Product Strategy
 

API Design Tour with Digital River and Apigee - June 26th, 2012

  • 1. API Design Tour: Digital River Minnetonka, MN, USA Brian Mulloy Apigee @landlessness @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, 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
  • 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?
  • 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

Editor's Notes

  1. Creative Commons Attribution-Share Alike 3.0 United States License
  2. All long running requests are considered asynchronous and will be setup by an inbound call to be scheduled.So far, no polling
  3. No SDKs yet. Reference architecture is almost complete.