OverDrive API Design
OverDrive APIs take a pragmatic approach to web API design. We borrowed from and mixed design approaches from other modern web API design philosophies such as REST and hypermedia.
As best as we can define it, OverDrive APIs are “Pragmatic REST APIs”--they are RESTful, hypermedia-driven and pragmatic, as defined in the following sections.
RESTful Design
One major source of influence on our API design is REST, an architectural style of API design first proposed by Roy Fielding. RESTful applications are designed to work the way the web works, using hyperlinks and HTTP verbs (GET, POST, PUT and DELETE) to operate on resources (content).
Hypermedia Design
The most distinctive characteristic of hypermedia design is the use of embedded ‘links’ within the returned message content. In simplistic terms, hypermedia design means that the message content contains data and additional metadata (links) and/or application flow options.
The web works this way. The web is a distributed hypermedia application, where end-users browse content by following embedded links. In the same way, hypermedia API design allows client applications to follow links in order to “browse” content.
In our context, this simply means we return data and metadata (links) in each response. Our API responses communicate the raw information as well as direction on how to navigate within it.
One advantage of this type of hypermedia design is that clients are not expected to construct URLs. As long as client applications understand the links and their relationship to the requested resource, they can simply ‘surf’ to the next valid resource.
Pragmatic Design
One downside of pure hypermedia design is that it isn’t quite as efficient as some of the more practical web API designs and requires discipline on the part of client applications and application developers. As a result, OverDrive has taken a pragmatic approach to API design. We try to keep things simple and client-centric by including well-defined entry points (story paths) in the OverDrive APIs.
Versioning
To support future changes, we’ve included a version number in the URL paths for all our APIs. We may add new fields or links to the API responses without changing the version number, and will prefer to introduce new functionality with these kinds of non-breaking changes.
As the APIs grow and evolve over time, however, it may be necessary to introduce changes that would break the API “contract” with existing clients. These necessary breaking changes will result in a change to the version number in the URL. Old versions will continue to be supported for a time, to allow existing clients the chance to transition to the new version.
JSON
In keeping with our pragmatic API design approach, we have chosen to support JSON as our response format. We decided not to support other formats because JSON is clearly winning the modern web API format war. JSON is universally accepted as a ‘front-end’ language, even when the back-end language is Java, Ruby, C#, Python, etc. It’s also much less verbose than XML, which is preferred for mobile applications.
Note: All API responses are UTF-8 encoded.
In summary, we think our pragmatic approach to design combines simplicity and ease of use for the clients with the scalability and loose coupling of hypermedia design.
