11436 SSO

API Design Tour: Digital River - On Designing URIs, Handling Formats, Pagination

Brian Mulloy
Jul 11, 2012

In the inaugural stop on our API Design Tour, we talked with the Digital River API Team about their approach to API design. The video and slides from our session are here. Below are some more of the design questions we put to the team. 

How do you approach the design of the URI?

A key aspect of the URI design is a focus on nouns.

Notice the meme in the request shoppers/me. This is used as a reminder for a developer that they are doing something on behalf of a shopper; that the shopper’s app or browser is making the call.

Digital River also wanted to have a way to specify the fields you want back or to expand the default fields. See the ‘expand’ query parameter, which identifies that extra data. This is key to keeping payloads small.

A critical part of URI design is hypermedia. Digital River embraced hypermedia in API design but although the thinking was that level 3.0 of the  Richardson Maturity Model (RMM) is a bit too complex and leads to a high chattiness.

“I would claim that we are probably Martin Fowler RMM level 2.5” - @Rubes_MN

Digital River uses the hyperlinks to relay information about what the API is doing and where data comes from —they just don’t do that inside a collection because it’s hard to reference what URI references what part of data inside a collection.

Instead they made it contextual and have a more or less hierarchical structure. For example, in the code above, you see the array of “categories” and within that, there are “relations” with a link to the documentation for details about the category in question: e.g. https://developers.digitalriver.com/v1/shoppers/CategoriesResource.

The “level 2.5” approach appears to be working—developers are using it and there is a comfortable balance between a mobile app slowly parsing a huge response versus the API being too chatty. 

How do you handle multiple formats?

The default is XML. JSON is also supported as it’s familiar to mobile and web developers. Most newly developed APIs have JSON as the default, but XML is familiar to traditional back-end developers, so both formats are important.

Note that the specification is in the header not the URI but instead in the header:

How do you handle pagination?

 “You have to do pagination up front. Don’t skip it!” - @Rubes_MN 

While your test data may have 10 items, your production data will have hundreds. Realistically, no device is going to parse that much data. Digital River does pagination in query parameters:

How do you handle metadata in your response?

The response has total results and results per page, which allows you to accommodate scrolling.

Other metadata is the hypermedia. See “relation” in the example above—it is the documentation embedded in the response.  Most developers like developing by example, and using hypermedia in this way to return examples and information about what they can do next is very powerful.

Next time, we’ll look at how the Digital River team approached HTTP verbs (one of their most contentious decision points), versioning, and errors.

Scaling Microservices