July 2019
Volume 34 Number 7
[The Working Programmer]
Coding Naked: Naked Networking
By Ted Neward | July 2019
.jpg "Ted Neward")
Welcome back, NOFers. Last time, I delved into NakedObjects actions, which collect the business logic for a given business object into a method that the NOF framework makes available to the user for direct manipulation and use. To a certain degree, I want to continue that plunge, because in the stock NOF Angular client, the invocation of an action in the client somehow ends up on the server, from whence it can write changes to the database. Somehow, somewhere, a network traversal is made to get from client to server, and it’s important this be explored, lest it get buried beneath hype.
At the risk of one more clothing-optional pun, are you ready to network naked?
Really RESTing
To understand the NOF Restful API networking standard/protocol, you first need to grasp some key concepts. I want to discuss REST, but not the REST that’s commonly tossed around in a cavalier way by architects and marketing hype machines. I need to go back to its origins and examine the source material.
Back in 2000, when Roy Fielding published the doctoral dissertation that served as the birthplace of REST, a new networking movement was born, although, to be fair, it would be more accurate to say that an existing networking approach was dissected and described. Fielding’s dissertation is a masterful study of distributed systems design, and is highly recommended reading for anyone who wants to understand how to build distributed systems more effectively. The part that most people concern themselves with is in Chapter 5 of the document, entitled “Representational State Transfer (REST).” (The entire dissertation is available at bit.ly/1NbHM8Y or, if you prefer, you can jump directly to Chapter 5 at bit.ly/1eTY8AI.)
Readers new to Fielding’s dissertation will find Chapter 5 especially interesting (although, honestly, the entire document is interesting and definitely worth reading), because Fielding deliberately “builds up” the REST architectural style (and he is quite deliberate about terminology here) from scratch, starting with what he calls the null style: “the null style describes a system in which there are no distinguished boundaries between components.” He slowly works through a series of other styles, noting how in each case, there’s an element of the style that’s useful for building out the World Wide Web—which is the case study for REST.
The key area of the document to which you should turn your attention is in section 5.1.5, “Uniform Interface.” I quote the paragraph, in its entirety, here:
The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability. The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
There’s a pretty hefty amount of concept to be unpacked here, but it’s the last sentence in particular that provides the key to understanding the NOF Restful API: “hypermedia as the engine of application state” means that the entire state of the network interaction is stored in a hypermedia document, shared between the client and the server. In traditional Web scenarios, that hypermedia document is HTML, sent back to the client, with no further traces of client identity left on the server, which in turn allows the server to be entirely stateless with respect to the client. (It’s for this reason of statelessness, by the way, that Fielding chooses to ignore the concept of cookies-as-client-identifiers on the server; in fact, both Fielding—and the HTTP standards—ignore cookies entirely.)
What this means, in practice, is that if a network interaction is going to characterize itself as “RESTful,” it needs to obey this principle of “uniform interface” and capture all state in hypermedia—that is to say, in a document format that contains the “next steps” allowed by the client, a document that’s exchanged between client and server.
(By the way, take note that Fielding has made it clear that REST is not always superior: “The REST interface is designed to be efficient for large-grain hypermedia data transfer, … but [results] in an interface that is not optimal for other forms of architectural interaction.” You will not hurt Fielding’s feelings if you use something other than REST for your next project.)
Restful API
The NOF Restful API, described in Fielding’s dissertation, describes an HTTP-based protocol that looks to embrace REST principles with all their benefits and drawbacks. Specifically, the Restful API constrains all of its communication around the hypermedia-as-the-engine-of-application-state (dubbed HATEOAS by REST practitioners and voted “Worst Acronym Ever” by the author of my personal blog), so that each exchange from a NakedObjects client is done in a full hypermedia request, and results in a full hypermedia document result. The easiest way to see this, of course, is to see it in action, so if the NOF Conference project isn’t already running on your machine, fire it up. This time, however, instead of pointing the browser to localhost:5001, where the Angular project will be downloaded to your browser, point it at localhost:5000 instead, which is the port on which the server is listening for Restful API requests from the browser.
The initial request, https://localhost:5000, yields the JSON-based result shown in Figure 1.
Figure 1 The Initial Hypermedia Request
{
"links":[
{
"rel":"self",
"method":"GET",
"type":"application/json;
profile=\"urn:org.restfulobjects:repr-types/homepage\"; charset=utf-8",
"href":"https://localhost:5000/"
},
{
"rel":"urn:org.restfulobjects:rels/user",
"method":"GET",
"type":"application/json; profile=\"urn:org.restfulobjects:repr-types/user\";
charset=utf-8",
"href":"https://localhost:5000/user"
},
{
"rel":"urn:org.restfulobjects:rels/services",
"method":"GET",
"type":"application/json; profile=\"urn:org.restfulobjects:repr-types/list\";
charset=utf-8; x-ro-element-type=\"System.Object\"",
"href":"https://localhost:5000/services"
},
{
"rel":"urn:org.restfulobjects:rels/menus",
"method":"GET",
"type":"application/json; profile=\"urn:org.restfulobjects:repr-types/list\";
charset=utf-8; x-ro-element-type=\"System.Object\"",
"href":https://localhost:5000/menus
},
{
"rel":"urn:org.restfulobjects:rels/version",
"method":"GET",
"type":"application/json; profile=\"urn:org.restfulobjects:repr-types/version\";
charset=utf-8",
"href":https://localhost:5000/version
}],
"extensions":{}
}
That’s a fat stream of gibberish, at least until it gets unpacked. But consider the structure that’s already apparent: It’s a JSON document, consisting of a root object that has two fields, “links” and “extensions.” The latter is empty, but the former is an array of “rel”/“method”/“type”/“href” fields, in this case five of them, all GET requests, with the “href” field offering up … well, exactly what it sounds like, a hyperlink reference.
Let’s try one of the simpler hyperlinks, the last one listed, which has “version” in the link. Popping that into the browser bar yields the results shown in Figure 2.
Figure 2 A Simple Hyperlink
{
"specVersion":"1.1",
"implVersion":"8.1.1\r\n",
"links":[
{
"rel":"self",
"method":"GET",
"type":"application/json;
profile=\"urn:org.restfulobjects:repr-types/version\";
charset=utf-8",
"href":https://localhost:5000/version
},
{
"rel":"up",
"method":"GET",
"type":"application/json;
profile=\"urn:org.restfulobjects:repr-types/homepage\";
charset=utf-8",
"href":https://localhost:5000/
}
],
"extensions":{},
"optionalCapabilities":{
"protoPersistentObjects":"yes",
"deleteObjects":"no",
"validateOnly":"yes",
"domainModel":"simple",
"blobsClobs":"attachments",
"inlinedMemberRepresentations":"yes"
}
}
Sure enough, it’s more of the same: This time the top-level object has “specVersion” and “implVersion” for the versions of the Restful Objects Specification, plus the “links” array you saw earlier (along with a few other fields that aren’t relevant to the discussion at hand).
If, on the other hand, you navigate to the “user” link mentioned in the first request (https://localhost:5000/user), you get what’s shown in Figure 3.
Figure 3 Results from the User Link
{
"links":[
{
"rel":"self",
"method":"GET",
"type":"application/json; profile=\"urn:org.restfulobjects:repr-types/user\";
charset=utf-8",
"href":"https://localhost:5000/user"
},
{
"rel":"up",
"method":"GET",
"type":"application/json;
profile=\"urn:org.restfulobjects:repr-types/homepage\";
charset=utf-8",
"href":"https://localhost:5000/"
}
],
"extensions":{},
"userName":"",
"roles":[]
}
This provides the now-familiar “links” array, along with “userName” and “roles.”
To get to any objects of interest, such as my speakers, in the Angular application, I can eye-scan the menu that’s presented off of the homepage. To the Restful API, this means I need to examine the “menu” link from the homepage to see the options. Within that returned JSON (which I’ll omit here to avoid wasting more column inches on unformatted JSON output), I get a “value” array that consists of several objects, each of which have a “title” (the menu item text), such as “Speakers” and “Talks,” and a corresponding “href,” which gives me links to the SpeakerRepository and TalkRepository, respectively. Not surprisingly, these links in turn provide links to the actions offered up by those services (each within its own submenu), and so on.
In short, the Restful API provides exactly what Fielding originally described in the REST chapter: hypermedia, in this case in the form of JSON documents containing embedded links, as the engine of the application state. This is as close to REST as you get, without building your own browser. (Which, technically, when you think about it, is exactly what a Naked Objects client is: a browser built for interaction with domain objects instead of HTML.)
The Restful API isn’t the first time this kind of interaction has been discussed, by the way; the OData specification pioneered by Microsoft was another such effort that (unfortunately) fell on the rocks among the non-Microsoft platforms in the world. But before that, numerous digiterati spoke of how to accomplish this same kind of interaction using JSON or RSS XML.
One of the clear benefits of this approach is in testing: To test a particular endpoint, if the entire service is stateless, you need only submit the properly attributed and parameterized request and the server should respond with the correct response. In some cases, particularly for those services that must remain behind an authorization wall, this may require an extra request/response cycle, but it certainly still comes out ahead compared to the deeply nested series of calls that an RPC-style HTTP API normally commands.
Wrapping Up
There are a number of interesting concepts still remaining in the Naked Objects Framework, but that’s true of just about any topic this column ever covers, and it’s time to move onward. Bear in mind that the point of this series is not a blatant push for you to use NOF in your own projects—although I heartily endorse the idea if the circumstances favor it—but for you to also consider how you might use some of these concepts in your own custom projects. Naked objects, as you’ve already seen, are the ultimate expression of the domain object concept, and if your project has reached the state of ubiquitous language and can clearly identify the domain objects, but expects a certain amount of churn and change over time as the business grows and evolves, it might be useful to build a mini-NOF framework to display and manipulate those objects. Similarly, it’s all but impossible to have an inconsistent user interface when the UI is generated on-the-fly by examining the objects at runtime. And let’s not get started on versioning—having a single client that knows how to display and manipulate objects based on their runtime characteristics is strong proof against needing to roll out a new client version every time a domain object’s properties or actions change in response to business requirements.
Love them or hate them, Naked Objects is a powerful tool to have in your belt, and something every developer should spend some time exploring before moving on.
Speaking of which, it’s high time we were moving on, as well. For now … happy coding!
Ted Neward is a Seattle-based polytechnology consultant, speaker and mentor. He has written a ton of articles, authored and co-authored a dozen books, and speaks all over the world. Reach him at ted@tedneward.com or read his blog at blogs.tedneward.com.
Thanks to the following technical expert for reviewing this article: Richard Pawson