I n the preceding section, I mentioned that our API will not be RESTful; let me explain why. While almost all constraints of REST make sense for modern APIs, HATEOAS does not.

Roy Fielding outlined the REST constraints in his doctoral dissertation paper titled Architectural Styles and the Design of Network-based Software Architectures, which you can access at www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. This was back in the year 2000, before search engines such as Yahoo!, Lycos, Infoseek, AltaVista, Ask Jeeves, and Google became prominent. The HATEOAS constraint made sense then, as it allows website visitors to use the list of links to navigate from any one page to any other page.

However, the HATEOAS constraint makes less sense for APIs. Developers who are looking to use our API today are likely to refer to the API documentation on our project's website, rather than infer it from the server response. They're also likely to hardcode URLs into their application code, rather than obtaining them from links provided by the server.

In other words, HATEOAS makes sense for human users, but is not so great for code. In fact, strictly abiding by the HATEOAS constraint would mean our response must include information that is not useful to the application. This will increase network latency without providing any tangible benefits.

Therefore, our API will, by design, not comply with the HATEOAS constraint. Thus, we cannot call our API RESTful.

This can be confusing because many APIs that claim to be RESTful in fact aren't (how many APIs have you used that actually return a list of endpoints with each request? I'd guess none). The lesson to take away is that we should analyze each REST constraint against our API, apply those that make sense, but understand that an API doesn't have to be RESTful to be "good."