We were thrilled to kick off our API Design Tour series in June with a fantastic discussion with Eric Roubal (@Rubes_MN) and Doug Messner (@dougdriv) of the Digital River API Team. The video and slides are here.
We talked with the team about the key topics and decisions that we’ve seen folks encounter in their API initiatives and explored their thought processes, challenges and successes.
We got fantastic insights from a team that has been implementing and evolving their API for close to 10 years for their global commerce platform. Digital River operates in 160 countries, 30 languages, and 40 currencies. It currently supports 3-4 million API calls per day; 80% of which are outbound calls.
Who are your target developers? Internal? Partners? Open?
The Digital River “transparent commerce” API is open to all developers for experimentation and innovation. Developers who establish a business relationship with Digital River or have an existing relationship can take their applications to market.
The primary focus is on the worldwide community of app developers who want to integrate a shopping cart experience into their apps (using APIs).
A framework for partners allows partners to create plug-ins to the global commerce platform – for example, Gigyaprovides social sign-in and Bazaarvoice provides customer reviews. APIs were necessary at first for working with partners and clients; and now using APIs, Digital River outsources innovation.
Internal APIs are also deployed to provide a structured environment for internal access to the global commerce platform.
APIs for “in-app” and “contextual commerce”
Digital River’s “transparent commerce” API allows developers to do “in-app API-based commerce” by allowing them to integrate a shopping cart experience as part of their apps.
Traditionally Digital River has had Plain Old XML (POX)-based APIs. Newer REST-based APIs allow innovators to use Digital River-hosted catalogs from within apps thereby moving commerce onto all kinds of devices – TVs, phones, etc. The team talked about it in terms of doing “contextual commerce.“
The team’s overall design philosophy is one that provides easy to use, self-service, self-documenting APIs with a low touch for implementation.
They chose REST-inspired APIs for ease of use for developers. Self-service, self-testing, and self-integration support is important because it leads to better adoption, making APIs more accessible and opening up to a broader group of developers.
The team aimed to avoid letting the perfect be the enemy of good. At a certain point, you have to “take a stand, take a stab and go with it.”
Debates and deliberations
Before we got into the nitty-gritty of URI design, pagination, versioning, and so on, I was curious what aspects of API design generated the most discussion.
Without pause, Eric’s response was “schema versus no-schema.” For those of us coming from a simple Web API background, that may not be a familiar dichotomy.
Schemas started with DTDs – specifications for SGML, HTML and XML; then XSD schemas which were XML descriptions written in XML. They were both complicated, and difficult to read.
The non-schema Web API approach, and the way in which Digital River implements it, allows for simpler conventions instead of cumbersome configurations. Content is readable and easy to understand.
Another big topic of discussion was about how far to decompose the data. You’re probably building your API against a legacy system, which typically is more than 2 or 3 years old. It has objects and an object graph stored in a database, which you need to decompose. You’ll have to handle the references between database records in the process. The nature of the legacy systems, business requirements (especially mobile devices), and the basic tenets of the overall design philosophy continue to drive and refine the team’s decisions here.
PUT versus POST was another huge topic of discussion. We’ll talk more about that later.
From there, we started in on the nitty-gritty aspects of design, which are topics we’ll cover in another post. Meanwhile, very big thanks again to @Rubes_MN and @dougdriv for sharing their insights and experiences with a mature, yet evolving API initiative!