API Design Tour: Digital River

API Design Tour:Digital River

Brian Mulloy@landlessness

Apigee@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/xmlXML 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/ProductsResource, "uri":"https://api.digitalriver.com/v1/shoppers/me/categories/59031600/products" }

<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 POSTWe 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, 201fido found, full replace, 204

Factors in PUT vs. POST decision:• Idempotence• Factory URLs• Full Replacement

Which convention do you use for response attribute names?

createdAtfirstNamelastName

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 layerAuthorization: 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 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:

@landlessness

[email protected]

@apigee