When REST API design goes from helpful to harmful

REST may be a somewhat non-negotiable standard in web API development, but has it fostered overreliance? Learn why other design styles could -- and should -- get an equal chance.

Software development depends on API communication, something that is often accomplished using REST-based design. Because REST is seen as an authoritative standard in web API development, two key questions arise: Does REST API design trap developers in a Golden Hammer situation, and, if so, what alternative approaches might help them break the cycle?

Software architect and acclaimed API design expert Arnaud Lauret, author of The Design of Web APIs, provides us his take on the relative value of committing to REST or taking a chance on newer approaches like WebSockets and GraphQL. We'll also look at some examples that illustrate when and how one protocol strategy might make more sense than another, such as web-centric versus internal development scenarios.

Is REST a Golden Hammer?

The Golden Hammer antipattern, which Lauret also calls the "law of the instrument," refers to the tendency for software teams or team members to intractably rely on a single tool, framework, pattern, protocol or development methodology without due consideration of alternative approaches that could prove better.

Image of Arnaud Lauret, author of 'The Design of Web APIs' Arnaud Lauret, author,
The Design of Web APIs

Granted that REST is such a predominant standard in web application design and communication, it is frequently the only realistic means of connecting web applications with external APIs, users and services via the internet. Despite the proven capability of alternatives like WebSockets, developers who take this approach to API builds may struggle to communicate with HTTP-only systems or even bypass network security barriers.

"There are security gateways [with components] that only speak HTTP, and do not understand WebSockets," Lauret explained. "That's a pity for the people working in that organization, because they may want to use it for totally valid reasons."

While it's certainly true that a large majority of organizations depend on REST-based APIs, Lauret cautioned that developers should avoid cultivating an unhealthy overreliance on REST API design and, by association, HTTP.

"If you want to communicate with the outside world nowadays -- even asynchronously -- you'll likely have to use HTTP," Lauret explained. "[But], inside your organization, be open minded and use other things. And maybe later we will be able to use other protocols than HTTP to [employ] asynchronous APIs outside of your organization."

GraphQL isn't always the answer

Lauret explained that organizations typically use GraphQL to create private, high-performance APIs that are built using a backends-for-frontends design pattern. However, there are existing collections of public GraphQL-based APIs; these include open APIs made available by GitHub and, of course, Facebook -- the original pioneers of GraphQL.

Book cover of 'The Design of Web APIs' by Arnaud LauretClick here, and get a discount
with the code 'nltechtarget21.'

Though an increasing number of developers are finding ways to make GraphQL and public REST APIs work together, Lauret warned that GraphQL carries as much risk of abuse as REST. If implemented poorly or inappropriately, he explained, GraphQL API can create complicated networks of requests that could make for an unwieldy management challenge.

Lauret said that teams should carefully analyze the issues they are trying to address and avoid vaguely referring to things like "slow REST requests" without qualifying metrics. It may come to light, he said, that using REST isn't even the problem -- rather, it's a problem in the underlying architectural design.

"Using GraphQL, gRPC, WebSockets or asynchronous API's will not solve your design issues," he stressed. "You have to design the solution to that problem -- not just choose a technical stack."

This problem, however, is not at all specific to the choice between REST and GraphQL. Lauret ultimately believes that teams need to adopt an incremental, patient and learning-based process to introduce any new technology, such as GraphQL-based APIs -- which he stresses in his book.

"Introducing a new technology in your environment requires that you teach people to use it, and that will take time," he said. "Hopefully, in the long run, people will know how to use it."

Read this excerpt from Lauret's book, The Design of Web APIs, to learn more about the guiding principles that should influence API design style choices.

Dig Deeper on API design and management

Software Quality
Cloud Computing