A Guide to REST & API Design

CA recently released a new eBook A Guide to REST & API Design that is based (in part) on a talk I gave at the 2012 Code PaLOUsa in Louisville, KY. The approach is a bit atypical for most REST papers or presentations. I decided to focus on some of the broader issues around design in general and then relate that to Fielding’s REST style for distributed software.

In the process of offering up guidance on how to design and implement APIs for the Web, I call on advice from psychologist Abraham Maslow, industrial designers Charles and Ray Eames and human-computer interaction guru Donald Norman. They all bolster many of the key principles Roy Fielding relied upon when he wrote his 2000 dissertation Architectural Styles & the Design of Network-based Software Architectures – the one that contains the definition of REST (Representational State Transfer) that so many talk about today.

Maslow’s Hammer There are many instances in our lives where we do things a certain way simply because “that’s the way we’ve always done it”. Nothing wrong with that except that sometimes we need to break out of routine, think differently about the task in front of us and try something new.

When discussing the challenge of taking new approaches and developing new skills with colleagues in the therapy field, Abraham Maslow explained the problem this way: “[I]t is tempting, if the only tool you have is a hammer, to treat everything like a nail.” Fielding voices basically the same idea in the introduction to his dissertation: “Consider how often we see software projects begin with the adoption of the latest fad in architectural design, and only later discover whether or not the system requirements call for such an architecture.”

The first challenge to exploring REST is getting past the way many of us have been thinking about and implementing Web-based APIs.

Eames’ Constraints When it comes to actually designing the application interface, an important guiding principle is adhering to a set of pre-established constraints. Paradoxically, constraints give you additional freedom when creating a design. Great designers know this, too.

The American design team Charles and Ray Eames had a reputation for looking at things in new ways in their contributions to modern architecture, furniture, industrial and graphic design and other fields. When asked about the keys to their success, Charles focused on the role constraints play in design: “[O]ne of the few effective keys to the design problem – the ability of the designer to recognize as many of the constraints as possible – [is a] willingness and enthusiasm for working within these constraints.”

Especially in situations where your are designing for wide-scale use, relying on constraints can actually be quite liberating. And this applies to creating APIs for the Web, too. Often Web APIs form a backbone or service to be used by many different client applications. It is very difficult to try to get all developers to code the same way, using the APIs in the same manner, when developers never meet each other. However, it is much easier to implement a set of constraints that all developers can abide by when they build their own applications.

Fielding’s REST Fielding understood the value of thinking in a new way and the importance of constraints. In establishing his REST style he focused on the interaction between connectors (e.g. Web server, proxies and browsers) instead of the interaction between components (e.g. databases, file systems and source code). This was a new way of thinking about the problem. “[REST] is achieved by placing constraints on connector semantics where other styles have focused on component semantics.”

Along with a focus on connectors, Fielding added a set of overall constraints for connecting parts to the network – the REST constraints. While many of these constraints are well-known (client-serverstatelesscacheuniform interfacelayered system and code-on-demand), it’s the “secondary” constraints that deserve special attention.

In a subset of the uniform interface constraint, Fielding went as far as creating constraints that dictate how connectors on the network can address each other (identifying resources), how the messages must be passed (manipulation through representation), what the message must look like (self-descriptive messages) and how workflow is executed (hypermedia as the engine of application state).

Even after more than 15 years, few developer frameworks or editing environments have caught up to this shift in thinking about how to design and implement APIs for the Web.

Norman’s Design Donald Norman, one of the first people to start talking about human-computer interaction design, has a wonderful point of view for design in general: “The value of a well-designed object is when it has such a rich set of affordances that the people who use it can do things with it that the designer never imagined.” For Norman, a great design is one that allow individuals to discover new uses, create new things and explore possibilities.

Fielding’s REST style has similar aims. Fielding’s reliance on connector constraints promotes adaptability and reuse on several levels. By constraining connectors, he liberates them for new uses even the initial designer of the API did not imagine. And that can result in APIs that last a long time and can support many interesting uses throughout this time.

There is more detail in the new A Guide to REST & API Design eBook and I hope these highlights will encourage you to download the eBook and discover the additional ideas and guidance to help you build your own long-lasting, adaptable Web APIs.

Recent Posts