Your API design depends fundamentally on knowing who is consuming the API and how they use it, writes Daniel Jacobson, director of engineering for the Netflix API in a recent article on The Next Web. This seems obvious, but Daniel goes on to write that the traditional "one-size-fits-all" resource-oriented API may not satisy the most important of your API consumers. Good API design is not merely about "resource modeling, payload format, how to version the system, and security," the more fundamental question is "who are the primary audiences for this API and how can we optimize for those audiences?"
Resource-oriented APIs may work for a "large set of unknown developers" but most organizations are actually addressing the needs of a "small set of known developers" with specific use-cases. "They may be engineers down the hall from the API team, a contracted company hired to develop an iPhone app, or an engineering team in a partnering company" writes Daniel and in this case there are opportunities to optimise the API.
Companies are increasingly introducing into their architecture an API orchestration layer which Daniel defines as "an abstraction layer that takes generically-modeled data elements and/or features and prepares them in a more specific way for a targeted developer or application." Daniel lists ome of the key principles of an orchestration layer as:
- Most APIs are designed by the API provider with the goal of maintaining data model purity. When building an [orchestration layer], be prepared to sometimes abandon purity in favor of optimizations and/or performance.
- Many APIs are designed by API teams to make it easier for the API team to support. When building an [orchestration layer], be prepared to potentially add complexity for the API team.
- It is important to understand the breadth of the audiences for the API. Depending on those constituents, you may only need the [orchestration layer]. In other cases, you may need the [one-size-fits-all] foundation in addition to the [orchestration layer].
The second principle brings to mind a common analogy from interface design with a "smart" video recorder where the complexity is increased on the inside of the box to make life easier for the user on the outside of the box.
Daniel closes his article by describing three common use-cases for the orchestration layer for device-specific wrappers, to support a query-based API and to provide experience-based APIs. Daniel writes that the device-specific wrapper is the most common use-case he has seen, quoting the example of an API wrapper optimized for an iPhone. Device-specific wrappers are generally provided by the API team for specific consumers. Query-based APIs conversely put the power onto API consumers "allowing [resources] to be queried against like a database through flexible parameters and payloads" that are under the control of the consumer.
Experience-based APIs are the model that Netflix has adopted and are a blend of the other two use-cases involving device-specific wrappers that are designed, implemented and owned by the API consumers. The division of responsibilities is split between the API team providing data in a generic re-usable way with consumers owning the data formatting and delivery.
Daniel concludes that the API team needs to view their consumers as design partners collaborating so that end-users get the best experience possible.