Client–Server

The first constraint to be added is one of the most common ones on network-based architectures: client–server. A server is in charge of handling a set of services, and it listens for requests regarding said services. The requests, in turn, are made via a connector by a client system needing one of those services (see Figure 1-1).

The main principle behind this constraint is the separation of concerns. It allows for the separation of front-end code (representation and possible UI-related processing of the information) from the server-side code, which should take care of storage and server-side processing of the data.

This constraint allows for the independent evolution of both components, offering a great deal of flexibility by letting client applications improve without affecting the server code and vice-versa.

Stateless

The constraint to be added on top of the previous one is the stateless constraint (see Figure 1-2). Communication between client and server must be stateless, meaning that each request done from the client must have all the information required for the server to understand it, without taking advantage of any stored data.

Although at first glance this constraint might seem nothing but good, as what normally happens, there is a trade-off. On one hand, benefits are gained by the system, but on the other side, network traffic could potentially be harmed by adding a minor overhead on every request from sending repeated state information. Depending on the type of system being implemented, and the amount of repeated information, this might not be an acceptable trade-off.

Cacheable

The cacheable constraint is added to the current set of constraints (see Figure 1-3). It proposes that every response to a request must be explicitly or implicitly set as cacheable (when applicable).

By caching the responses, there are some obvious benefits that get added to the architecture: on the server side, some interactions (a database request, for example) are completely bypassed while the content is cached. On the client side, an apparent improvement of performance is perceived.

The trade-off with this constraint is the possibility of cached data being stale, due to poor caching rules. This constraint is, again, dependent on the type of system being implemented.

Uniform Interface

One of REST’s main characteristics and winning points when compared to other alternatives is the uniform interface constraint. By keeping a uniform interface between components, you simplify the job of the client when it comes to interacting with your system (see Figure 1-4). Another major winning point here is that the client’s implementation is independent of yours, so by defining a standard and uniform interface for all of your services, you effectively simplified the implementation of independent clients by giving them a clear set of rules to follow.

Said rules are not part of the REST style, but there are constraints that can be used to create such rules for each individual case.

This benefit doesn’t come without a price, though; as with many other constraints, there is a trade-off here: having a standardized and uniform interface for all interactions with your system might harm performance when a more optimized form of communication exists. Particularly, the REST style is designed to be optimized for the Web, so the more you move away from that, the more inefficient the interface can be.

Layered System

REST was designed with the Internet in mind, which means that an architecture that follows REST is expected to work properly with the massive amount of traffic that exists in the web of webs.

To achieve this, the concept of layers is introduced (see Figure 1-5). By separating components into layers, and allowing each layer to only use the one below and to communicate its output to the one above, you simplify the system’s overall complexity and keep component coupling in check. This is a great benefit in all type of systems, especially when the complexity of such a system is ever-growing (e.g., systems with massive amounts of clients, systems that are currently evolving, etc.).

The main disadvantage of this constraint is that for small systems, it might add unwanted latency into the overall data flow, due to the different interactions between layers.

Code-on-Demand

Code-on-demand is the only optional constraint imposed by REST, which means that an architect using REST can choose whether or not to use this constraint and either gains its advantages or suffers its disadvantages.

With this constraint, the client can download and execute code provided by the server (such as Java applets, JavaScript scripts, etc.). In the case of REST APIs (on which this book focuses), this constraint seems unnecessary, because the normal thing for an API client to do is just get information from an endpoint, and then process it however needed; but for other uses of REST, like web servers, a client (i.e., a browser) will probably benefit from this constraint (see Figure 1-6).

All of these constraints provide a set of virtual walls within which an architecture can move and still gain the benefits of the REST design style.

But let’s take a step back. I initially defined REST as a design style for representational state transfer; in other words, you transfer the state of things by using some kind of representation. But what are these “things”? The main focus of a REST architecture is the resources, the owners of the state that you’re transferring. Just like in a real state (almost), it’s all about resources, resources, resources.

Representations

At its core, a representation is a set of bytes, and some metadata that describes these bytes. A single resource can have more than one representation; just think of a weather service report (which could act as a possible resource).

Now that the resource’s structure is defined, here are a few possible representations of the same resource:

Custom pipe-separated values:

And there could be many more. They all successfully represent the resource correctly; it is up to the client to read and parse the information. Even when the resource has more than one representation, it is common for clients (due to simplicity of development) to only request one of them. Unless you’re doing some sort of consistency check against the API, there is no point in requesting more than one representation of the same resource, is there?

There are two very popular ways to let the client request a specific representation on a resource that has more than one. The first one directly follows the principles described by REST (when using HTTP as a basis), called content negotiation, which is part of the HTTP standard. The second one is a simplified version of this, with limited benefits. For the sake of completeness, I’ll quickly go over them both.

Resource Identifier

The resource identifier should provide a unique way of identification at any given moment and it should provide the full path to the resource. A classic mistake is to assume it’s the resource’s ID on the storage medium used (i.e., the ID on the database). This means that you cannot consider a simple numeric ID as a resource identifier; you must provide the full path, and because we’re basing REST on HTTP, the way to access the resource it to provide its full URI (unique resource identifier) .

There is one more aspect to consider: the identifier of each resource must be able to reference it unequivocally at any given moment in time. This is an important distinction, because a URI like the following might reference Harry Potter and the Half Blood Prince for a certain period of time, and then Harry Potter and the Deathly Hollows 1 year later.:

This renders that URI as an invalid resource ID. Instead, each book needs a unique URI that is certain to not change over time; for example:

The identifiers are unique here, because you can safely assume that the author won’t publish more books with the same title.

And to provide a valid example for getting the last book, you might consider doing something like this:

The preceding URI references the lists of books, and it asks for only one, sorted by its publication date, thus rendering the last book added.

Actions

Identifying a resource is easy: you know how to access it and you even know how to request for a specific format (if there is more than one); but that’s not all that REST proposes. Since REST is using the HTTP protocol as a standing point, the latter provides a set of verbs that can be used to reference the type of action being done over a resource.

There are other actions, aside from accessing, that a client app can take in the resources provided by an API; these depend on the service provided by the API. These actions could potentially be anything, just like the type of resources handled by the system. Still, there is a set of common actions that any system that is resource-oriented should be able to provide: CRUD (create, retrieve, update, and delete) actions.

That said, a client may or may not support all of these actions; it depends on what needs to be achieved. For instance, web browsers—a clear and common example of a REST client—only have support for GET and POST verbs from within the HTML code of a page, such as links and forms (although using the XMLHttpRequest object from JavaScript would provide support for the major verbs mentioned earlier).

Hypermedia in the Response and Main Entry Point

To make REST’s interface uniform, several constraints must be applied. One of them is Hypermedia as the Engine of Application State, also known as HATEOAS . I’ll go over what that concept means, how it is meant to be applied by a RESTful system, and finally, how you end up with a great new feature that allows any RESTful system client to start the interaction knowing only a single endpoint of the entire system (the root endpoint).

Again, the structure of a resource contains a section called metadata ; inside that section, the representation of every resource should contain a set of hypermedia links that let the client know what to do with each resource. By providing this information in the response itself, the next steps any client can take are there, thus providing an even greater level of decoupling between client and server.

Changes to the resource identifiers, or added and removed functionalities, can be provided through this method without affecting the client at all, or at worst, with minimal impact.

Think of a web browser: all it needs to help a user navigate through a favorite site is the home page URL; after that, the following actions are presented inside the representation (HTML code) as links. Those are the only logical next steps that the user can take, and from there, new links will be presented, and so on.

In the case of a RESTful service, the same thing can be said: by calling upon the main endpoint (also known as bookmark or root endpoint), the client will discover all possible first steps (normally things like resource lists and other relevant endpoints).

Let’s look at an example in Listing 1-1.

Root endpoint: GET /api/v1/

Now let’s look at the books list endpoint’s results in Listing 1-2: GET /api/v1/books

Note that the full list of authors is not accessible through this endpoint; this is because for this particular use case, it’s not needed, so the API just doesn’t return it. It was present on the root endpoint, though, so if the client needs it when displaying the information to the end-user, it should still have it available.

Each link from the preceding example contains an attribute specifying the content-type of the representation of that resource. If the resources have more than one possible representation, the different formats could be added as different links inside each resource’s metadata element, letting the client choose the most adequate to the current use case, or the type could change based on the client’s preferences (content negotiation).

Note that the earlier JSON structure (more specifically, the metadata elements’ structure) is not important. The relevant part of the example is the information presented in the response. Each server has the freedom to design the structure as needed.

Not having a standard structure might harm the developer experience while interacting with your system, so it might be a good idea to adopt one. This is certainly not enforced by REST, but it would be a major point in favor of your system. A good standard to adopt in this case would be Hypertext Application Language , or HAL,⁷ which tries to create a standard for both XML and JSON when representing resources with those languages.

Communication’s Protocol

This is one of the most basic aspects of the interface. When choosing a communication protocol, it’s always a good idea to go with one that is familiar to the developers using the API. There are several standards that already have libraries and modules available in many programming languages (e.g., HTTP, FTP, SSH, etc.).

A custom-made protocol isn’t always a good idea because you’ll lose that instant portability in so many existing technologies. That said, if you’re ready to create support libraries for the most used languages, and your custom protocol is more efficient for your use case, it could be the right choice.

In the end, it’s up to the API designer to evaluate the best solution based on the context in which he’s working.

In this book, you’re working under the assumption that the protocol chosen for REST is HTTP.¹ It’s a very well-known protocol; any modern programming language supports it and it’s the basis for the entire Internet. You can rest assured that most developers have a basic understanding of how to use it. And if not, there is plenty of information out there to get to know it better.

In summary, there is no silver bullet protocol out there perfect for every scenario. Think about your API needs, make sure that whatever you choose is compatible with REST, and you’ll be fine.

Easy-to-Remember Access Points

The points of contact between all client apps and the API are called endpoints. The API needs to provide them to allow clients to access its functionalities. This can be done through whatever communications protocol is chosen. These access points should have mnemotechnic names to help the developer understand their purpose just by reading them.

Of course, the name by itself should never be a replacement for a detailed documentation, but it is normally considered a good idea to reference the resource being used and to have some kind of indicator of the action being taken when calling that access point.

The following is a good example of a badly named access point (meant to list the books in a bookstore):

This example uses the HTTP protocol to specify the access point, and even though the entity used (books) is being referenced, the action name is not clear; action1 could mean anything, or even worse, the meaning could change in the future, but the name would still be suitable, so any existing client would undoubtedly break.

A better example—one that follows REST and the standards discussed in Chapter 1—would be this:

This should present the developer with more than enough information to understand that a GET request into the root of a resource (/books) will always yield a list of items of this type; then the developer can replicate this pattern into other resources, as long as the interface is kept uniform across all other endpoints.

Uniform Interface

Easy-to-remember access points are important, but so is being consistent when defining them. Again, you have to go back to the human factor when consuming an API: you’re a human too. So making the lives of the developers using your APIs easier is a must if you want anyone to use it, you can’t forget about the DX. That means you need to be consistent when defining endpoints’ names, request formats, and response formats. There can be more than one version for the latter two (more specifically, the response format is directly tied to the various representations a resource can have), but as long as the default is always the same, there will be no problems.

A good example of an inconsistent interface, even though not on an API, can be seen in the programming language PHP. It has underscore notation on most functions’ names, but the underscore is not used on some, so the developer is always forced to go back to the documentation to check how to write these functions (or worse, rely on his/her memory).

For example, str_replace is a function that uses an underscore to separate both words (str and replace), whereas htmlentities has no separation of words at all.

Another example of bad design practice in an API is to name the endpoints based on the actions taken instead of the resources handled; for example:

These examples clearly show the pattern that this API is following. And at first glance, they might not seem that bad, but consider how poor the interface is going to become as new features and resources are added to the system (not to mention if the actions are modified). Each new addition to the system causes extra endpoints to the API’s interface. The developers of client apps will have no clue as to how these new endpoints are named. For instance, if the API is extended to support the cover images of books, with the current naming scheme, these are all possible new endpoints:

And the list can go on. So for any real-world application, you can safely assume that following this type of pattern will yield a really big list of endpoints, increasing the complexity of both server-side code and client-side code. It will also hurt the system’s ability to capture new developers, due to the inherited complexity that it will have over the years.

To solve this problem and generate an easy-to-use and uniform interface across the entire API, you can apply the REST style to the endpoints. If you remember the constraints proposed by REST from Chapter 1, you end up with a resource-centric interface. And thanks to HTTP , you also have verbs to indicate actions.

You went from having to remember nine different endpoints to just two, with the added bonus of having all HTTP verbs being the same in all cases once you defined the standard; now there is no need to remember specific roles in each case (they’ll always mean the same thing).

Transport Language

Another aspect of the interface to consider is the transport language used. For many years, the de facto standard was XML; it provided a technology-agnostic way of expressing data that could easily be sent between clients and servers. Nowadays, there is a new standard gaining popularity over XML—JSON.

Why JSON ?

JSON has been gaining traction over the past few years (see Figure 2-1) as the standard Data Transfer Format. This is mainly due to the advantages that it provides. The following lists just a few:

• It’s lightweight. There are very little data in a JSON file that are not directly related to the information being transferred. This is a major winning point over more verbose formats like XML.²

• It’s human-readable. The format itself is so simple that it can easily be read and written by a human. This is particularly important considering that a focus point of the interface of any good API is the human factor (otherwise known as the DX).

• It supports different data types. Because not everything being transferred is a string, this feature allows the developer to provide extra meaning to the information transferred.

The list could go on, but these are the three main aspects that are helping JSON win so many followers in the developer community.

Even though JSON is a great format and is gaining traction, it’s not the silver bullet that will always solve all of your problems, so it’s also important to provide clients with options. And here is where REST comes to help.

Since the protocol you’re basing REST on is HTTP, developers can use a mechanism called content negotiation to allow clients to specify which of the supported formats they want to receive (as discussed in Chapter 1). This allows for more flexibility on the API and still keeps the interface uniform.

Going back to the list of endpoints , the last one talks about using a subresource as the solution. That can be interpreted in several ways, because not only is the language used to transfer the data important, but so is the structure that you give the data being transferred. My final advice for a uniform interface is to standardize the format used, or even better, follow an existing one, like Hypertext Application Language (HAL).

This was covered in Chapter 1, so refer back to it for more information.

How Is Extensibility Managed?

When extending the API, you’re basically releasing a new version of your software, so the first thing you need to do is let your users (the developers) know what will happen once the new version is out. Will their apps still work? Are the changes backward-compatible? Will you maintain several versions of your API online or just the latest one?

Once all these points are settled, then you can safely grow and extend the API.

Normally, going from version A to version B of an API by instantly deprecating version A and taking it offline in favor of version B is considered a bad move, unless, of course, you have very few client applications using that version.

A better approach for this type of situation is to allow developers to choose which version of the API they want to use, keeping the old version long enough to let everyone migrate into the newer one. And to do this, an API would include its version number in the resource identifier (i.e., the URL of each resource). This approach makes the version number a mandatory part of the URL to clearly show the version in use.

With that scheme, the first number is the only one that is really relevant to clients, since that’ll be the one indicating compatibility with their current version.

By having the latest version of MINOR and PATCH deployed on the API at all times, you’re providing clients with the latest compatible features and bug fixes, without making clients update their code.

So with that simple versioning scheme, the endpoints look like this:

Phase 1: Development of the Client

During the first phase, developers implement the required code to consume the API. It is very likely that a developer will have errors on the requests (things like missing parameters, wrong endpoint names, etc.) during this stage.

Those errors need to be handled properly, which means returning enough information to let developers know what they did wrong and how they can fix it.

A common problem with some systems is that their creators ignore this stage, and when there is a problem with the request, the API crashes, and the returned information is just an error message with the stack trace and the status code 500, as seen in Figure 2-5.

The response in Figure 2-5 shows what happens when you forget to add error handling in the client development stage. The stack trace returned might give the developer some sort of clue (at best) as to what exactly went wrong, but it also shows a lot of unnecessary information, so it ends up being confusing. This certainly hurts development time, and no doubt would be a major point against the DX of the API.

On the other hand, let’s take a look at a proper error response for the same error in Figure 2-6.

Phase 2: The Client Is Implemented and Being Used by End Users

During this stage in the life cycle of the client, you’re not expecting any more developer errors, such as using the wrong endpoint, missing parameters, and the like, but there could still be problems caused by the data generated by the user.

Client applications that request some kind of input from the user are always subject to errors on the user’s part, and even though there are always ways to validate that input before it reaches the API layer, it’s not safe to assume all clients will do that. So the safest bet for any API designer and developer is to assume there is no validation done by the client, and anything that could go wrong with the data will go wrong. This is also a safe assumption to make from a security point of view, so it’s providing a minor security improvement as a side effect.

With that mindset, the API implemented should be rock-solid and able to handle any type of errors in the input data.

The response should mimic that from phase 1: there should be an error indicator, an error message stating what’s wrong (and, if possible, how to fix it), and a custom error code. The custom error code is especially useful in this stage, since it’ll provide the client with the ability to customize the error shown to the end user (even showing a different but still relevant error message).

Accessing the System

There are some widely used authentication schemes out there meant to provide different levels of security when signing users into a system. Some of the most commonly known are Basic Auth with TSL, Digest Auth, OAuth 1.0a, and OAuth 2.0.

I’ll go over these and talk about each of their pros and cons. I’ll also cover an alternative method that should prove to be the most RESTful, in the sense that it’s 100% stateless.

Basic Auth with TSL

Thanks to the fact that you’re basing REST on HTTP for the purpose of this book, the latter provides a basic authentication method that most of the languages can support.

Keep in mind, though, that this method is aptly named, since it’s quite basic and works by sending the username and password unencrypted over HTTP. So the only way to make it secure is to use it with a secured connection over HTTPS (HTTP + TSL).

This authentication method works as follows (see Figure 2-7):

1. 1.

   First, a client makes a request for a resource without any special header.

    
2. 2.

   The server responds with a 401 unauthorized response, and within it, a WWW-Authenticate header, specifying the method to use (Basic or Digest) and the realm name.

    
3. 3.

   The client then sends the same request but adds the Authorization header, with the string USERNAME:PASSWORD encoded in base 64.

    

On the server side, there needs to be some code to decode the authentication string and load the user data from the session storage used (normally a database).

Aside from the fact that this approach is one of the many that will break the nonstateless constraint, it’s easy and fast to implement.

Note

When using this method, if the password for a logged in user is reset, then the login data sent on the request becomes old and the current session is terminated.

OAuth 1.0a

OAuth 1.0a is the most secure of the four nonstateless methodologies described in this section. The process is a bit more tedious than the ones described earlier (see Figure 2-8), but the trade-off here is a significantly increased level of security.

In this case, the service provider has to allow the developer of the client app to register the app on the provider’s web site. By doing so, the developer obtains a consumer key (a unique identifying key for his application) and the consumer secret. Once that process is done, the following steps are required:

1. 1.

   The client app needs a request token. The purpose is to receive the user’s approval and then request an access token. To get the request token, a specific URL must be provided by the server; in this step, the consumer key and the consumer secret are used.

    
2. 2.

   Once the request token is obtained, the client must make a request using the token on a specific server URL (i.e., http://provider.com/oauth/authorize ) to get authorization from the end user.

    
3. 3.

   After authorization from the user is given, then the client app makes a request to the provider for an access token and a token secret key.

    
4. 4.

   Once the access token and secret token are obtained, the client app is able to request protected resources for the provider on behalf of the user by signing each request.

    

For more details on how this method works, please refer to the complete documentation.¹⁷

A Stateless Alternative

As you’ve seen, the alternatives you have when it comes to implementing a security protocol to allow users to sign into a RESTful API are not stateless, and even though you should be prepared to make that commitment to gain the benefits of tried and tested ways of securing your application, there is a fully REST compatible way of doing it as well.

If you go back to Chapter 1, the stateless constraints basically imply that any and all states of the communication between client and server should be included on every request made by the client. This of course includes the user information, so if you want to have stateless authentication, then you need to include that in your requests as well.

If you want to ensure the authenticity of each request, you can borrow the signature step of OAuth 1.0a and apply it on every request by using a pre-established secret key between the client and the server and a MAC (Message Authentication Code) algorithm to do the signing (see Figure 2-9).

As you’re keeping it stateless , the information required to generate the MAC needs to also be sent as part of the request, so the server can re-create the result and corroborate its validity.

This approach has some clear advantages in our case, mainly:

• It’s simpler than both OAuth 1.0a and OAuth 2.0.

• Zero storage is needed, since any and all required information to validate the encryption needs to be sent on every request.

Async Advanced

Asynchronous programming is not just about making sure that you set up the callback function correctly, it also allows for some interesting flow control patterns that can be used to improve the efficiency of the app.

Let’s look at two distinct and very useful control flow patterns for asynchronous programming: parallel flow and serial flow.

Async I/O vs. Sync I/O

Both endpoints do exactly the same, only in a different manner (see Listing 3-11). The idea is to prove that even in such simple code, the event loop can handle multiple requests better when the underlying code makes use of the asynchronous I/O provided by the platform.

Listing 3-12 is the code of both endpoints; the API was written using Vatican.js.⁷

As you can see in Table 3-1, for even the simplest of examples, there are 812 more requests being served by the asynchronous code than in the synchronous code in the same amount of time. Another interesting item is that each request is almost 8 milliseconds faster on the asynchronous endpoint; this might not be a huge number, but considering the nonexistent complexity of the code you’re using, it’s quite relevant.

Dynamic Typing

Dynamic typing is a basic characteristic present in most common languages nowadays, but it’s no less powerful because of that. This little feature allows the developer to not have to think too much when declaring a variable; just give it a name and move on.

Listing 3-14 shows something you can’t do with a statically typed language.

Object-Oriented Programming Simplified

JavaScript it not an object-oriented language, but it does have support for some of these features (see Listing 3-14 and Listing 3-16). You’ll have enough access to objects to conceptualize problems and solutions using them, which is always a very intuitive way of thinking, but at the same time, you're not dealing with concepts like polymorphism, interfaces, or others that, despite helping to structure code, have proven to be dispensable when designing applications.

Whereas with other languages, like Java (a strongly object-oriented language), you would have to do what’s shown in Listing 3-16.

Much less verbose, isn’t it?

In Listing 3-17, let’s look at another example of the powerful object orientation that you have available.

You were able to encapsulate a simple behavior into an object and pass it into another object to automatically overwrite its default behavior. That’s something that’s built into the language; you didn’t have to write any specific code to achieve this feature.

The new Class construct from ES6

Tired of being laughed at and pointed at for not having a proper class construct for the OOP lovers, the good folks at Ecma International decided to create one. Actually, I’m just guessing, I don’t know why they decided to add it, but they did, so be happy about it or don’t, your call.

The point is: if you like solving your problems using OOP, now you have the most basic structure any OOP language provides, right at your fingertips. But don’t get too excited just yet, they’re not the same kind of classes you’d have in JAVA or any other fully OOP language. No, they’re just your basic, nothing-fancy type of classes, and let me explain with the following code sample:

Functional Programming Support

JavaScript is not a functional programming language; but then again, it does have support for some of its features (see Listings 3-18, 3-19, and 3-20), such as having first-class citizen functions, allowing you to pass them around like parameters, and returning closures easily. This feature makes it possible to work with callbacks, which, as you’ve already seen, is the basis for asynchronous programming.

Let’s look at a quick and simple functional programming example in Listing 3-19 (remember, JavaScript provides only some functional programming goodies, not all of them). Create an adder function.

Let’s look at a more complex example, an implementation of the map function, which allows you to transform the values of an array by passing the array and the transformation function. Let’s first look at how you’d use the map function.

Now let’s look at a possible implementation using the functional approach.

Duck Typing

Have you ever heard the phrase “If it looks like a duck, swims like a duck, and quacks like a duck, it probably is a duck”? Well then, it’s the same for typing in JavaScript. The type of a variable is determined by its content and properties, not by a fixed value. So the same variable can change its type during the life cycle of your script. Duck typing is both a very powerful feature and a dangerous feature at the same time.

Listing 3-22 offers a simple demonstration.

Native Support for JSON

This is a tricky one, since JSON actually spawned from JavaScript, but let’s not get into the whole chicken-and-egg thing here. Having native support for the main transport language used nowadays is a big plus.

Listing 3-23 is a simple example following the JSON syntax.

This particular feature is especially useful in several cases—for instance, when working with a document-based storage solution (like MongoDB) because the modeling of data ends up being native in both places (your app and the database). Also, when developing an API, you’ve already seen that the transport language of choice these days is JSON, so the ability to format your responses directly with native notation (you could even just output your entities, for that matter) is a very big plus when it comes to ease of use.

The list could be extended, but those are some pretty powerful features that JavaScript and Node.js bring to the table without asking too much of the developer. They are quite easy to understand and use.

Alternatives to MVC

MVC is a great architecture. Nearly every developer is using it or has used it for a web project. Of course, not everyone loves it, because it has suffered the same fate other popular things in the development community have suffered (Ruby on Rails, anyone?). If it becomes popular on the Internet, everyone is using it for everything—until they realize that not every project looks like an MVC nail, so you have to start looking at other shapes of hammers (other alternatives architectures).

But luckily, there are alternatives; there are similar architectural patterns that may better suit your needs, depending on the particular aspects of your project. Some of them are direct derivatives of MVC, and others try to approach the same problem from a slightly different angle (I say “slightly” because, as you’re about to see, there are things in common).

Hierarchical MVC

Hierarchical MVC⁴ is a more complex version of MVC in the sense that you can nest one MVC component inside another one. This gives developers the ability to have things like an MVC group for a page, another MVC group for the navigation inside the page, and a final MVC component for the contents of the page.

This approach is especially helpful when developing reusable widgets that can be plugged into components, since each MVC group is self-contained. It is useful in cases when the data to be displayed come from different related sources. In these cases, having an HMVC structure helps keep the separation of concerns intact and avoids coupling between components that shouldn’t be.

Let’s look at a very basic example. Think of a user reading a blog post and the related comments underneath it. There are two ways to go about it: with MVC or with HMVC.

With MVC , the request is done to the BlogPosts controller, since that is the main resource being requested; afterward, that controller loads the proper blog post model, and using that model’s ID, it loads the related comments models. Right there, there is an unwanted coupling between the BlogPosts controller and the comments model. You can see this in the diagram in Figure 4-8.

Figure 4-8 shows the coupling that you need to get rid of; it is clearly something that can be improved from an architectural point of view. So let’s look at what this would look like using HMVC (see Figure 4-9).

The architecture certainly looks more complex and there are more steps, but it is also cleaner and easier to extend. Now in step 3, you’re sending a request to an entirely new MVC component , one in charge of dealing with comments. That component will in turn interact with the corresponding model and with the generic view layer to return the representation of the comments. The representation is received by the BlogPost controller, which attaches it to the data obtained from the BlogPost model and sends everything back into the view layer.

If you want to create a new section in the blog showing specific blog posts and their comments, you could easily reuse the comments component.

All in all, this pattern could be considered a specialization of common MVC, and it could come in handy when designing complex systems.

Model–View–ViewModel

The Model–View–ViewModel pattern⁵ was created by Microsoft in 2005 as a way to facilitate UI development using WPF and Silverlight; it allows UI developers to write code using a markup language (called XAML) focusing on the User Experience (UX), and accessing the dynamic functionalities using bindings to the code. This approach allows developers and UX developers to work independently without affecting each other’s work.

Just like with MVC, the Model in this architecture concentrates the business logic, while the ViewModel acts as a mediator between the Model and the View, exposing the data from the Model. It also contains most of the view logic, allowing the ViewLayer to only focus on displaying information, leaving all dynamic behavior to the ViewModel (see Figure 4-10 for more details).

These days, the pattern has been adopted by others outside Microsoft, like the ZK framework in Java and KnockoutJS, AngularJS, Vue.js, and other frameworks in JavaScript (since MVVM is a pattern specializing in UI development, it makes sense that UI frameworks written in JavaScript are big adopters of this pattern).

Model–View–Adapter

The model–view–adapter⁶ (MVA) pattern is very similar to MVC, but with a couple of differences. Mainly, in MVC the main business logic is concentrated inside each model, which also contains the main data structure, with the controller in charge of orchestrating the model and the view.

In MVA, the model is just the data that you’re working with, and the business logic is concentrated in the adapter, which is in charge of interacting both with the view and the model. So basically, it consists of slimmer models and fatter controllers. But joking aside, this allows for a total decoupling of the view and the model, giving all responsibilities to the adapter.

This approach works great when switching adapters to achieve different behaviors on the same view and model.

The architecture for this pattern is shown in Figure 4-11.

Request/Response Handling

Regarding request and response handling, they usually both come in the same module. They are the basics of every HTTP application you intend to make. If you don’t know how to handle the HTTP protocol, you can’t move forward.

Writing code that listens in a specific port for HTTP traffic is simple; actually, Node.js provides all the tools you need, out of the box, to achieve the three preceding points. Then why do we need extra modules if we can easily do it ourselves? That’s a very valid question, and to be honest, it all depends on your needs. If the system you’re building is small enough, then it might be a good idea to build the HTTP server yourself; otherwise, it’s always good to use a well-tested and tried module. These modules also solve other related issues for you, such as routes handling, so going with a third-party module might be a good choice.

Routes Handling

Routes handling is tightly coupled with request and response handling; it’s the next step in the processing of the request. Once you translate the HTTP message into an actual JavaScript object that you can work with, you need to know which piece of code needs to handle it. This is where routes handling comes in.

Usually, routing frameworks provide some sort of templating language that allows developers to set up named parameters in the route template. Later the framework will match the requested URLs to the templates, taking into consideration those variable parts added. Different frameworks add different variations of this; you’ll see some of them in a bit.

Middleware

This is the name that the pre-processing chain normally gets in the Node.js world, and that is because the Connect¹ framework (which is the framework on which most other web frameworks are based) has this functionality.

I already talked about this topic in the previous chapter, so let’s look at some examples (Listing 5-1) of middleware functions that are compatible with Connect-based frameworks:

The two examples from Listing 5-1 are different, but at the same time they share a common function signature. Every middleware function receives three parameters: the request object, the response object, and the next function. The most interesting bit here is the last parameter, the next function, calling it is mandatory unless you want to end the processing chain right there. It calls the next middleware in the chain, unless you pass in a value, in which case it’ll call the first error handler it finds and it’ll pass it the parameter (normally an error message or object).

The use of middleware is very common for things like authentication, logging, session handling, and so forth.

Up-to-Date Documentation

As I’ve already discussed, keeping up-to-date documentation of the API’s interface is crucial if you want developers to use your system. I’ll go over some modules that will help in that area. There is no silver bullet, of course; some of modules add more overhead than others, but the main goal is to have some sort of system that updates its documentation as automatically as possible.

Hypermedia on the Response

If you want to follow the REST style to the letter, you need to work this into your system. It is one of the most forgotten features of REST—and a great one, since it allows for self-discovery, another characteristic of a RESTful system.

For this particular case, you’ll go with a pre-defined standard called HAL (covered in Chapter 1), so you’ll be checking out some modules that allow you to work with this particular format.

Response and Request Validation

I’ll also go over some modules that will let you validate both the response and the request format. Our API will work with JSON alone, but it’s always useful to validate the structure of that JSON in the request due to errors in the client application and in the response to ensure that there are no errors in the server side after code changes.

Adding a validation on every request might be too big of an overhead, so an alternative might be a test suite that takes care of doing the validation when executed. But the request format validation will have to be done on every request to ensure that the execution of your system is not tainted by an invalid request.

The List of Modules

We won’t compare them because it’s not an easy thing to do considering that some modules only handle one thing, whereas others take care of several things. So after going over them, I’ll propose a combination of these modules, but you will have enough information to pick a different combo if it better fits your problem.

HAPI

HAPI is a framework used for building both applications and services (APIs). It’s actively maintained and has more than half a million downloads a month.

Table 5-2 shows more details about this particular framework.

Table 5-2

HAPI Module Information

Category	Request/Response handler, Routes handler
Current version	17.4.0
Description	HAPI is a configuration-centric web framework designed to create any kind of web application, including APIs. The main goal of HAPI is to allow developers to focus on coding the logic of an application, leaving infrastructure code to the framework.
Home page URL	http://hapijs.com/
Installation	Installing the framework is simple using npm: $ npm install hapi That’s it. HAPI is installed in your application. You can also run the following command to get the dependency added automatically to your package.json file: $ npm install hapi --save

Code Examples

After installation, the most basic thing you can do to initialize the system and get your server up and running is shown in Listing 5-2.

'use strict';

const Hapi=require('hapi');

// Create a server with a host and port

const server=Hapi.server({

    host:'localhost',

    port:8000

});

// Start the server

async function start() {

    try {

        await server.start();

    }

    catch (err) {

        console.log(err);

        process.exit(1);

    }

    console.log('Server running at:', server.info.uri);

}

start()

Listing 5-2

Simple Server Code with HAPI.JS

As you can see, this example is quite basic, but the steps required to initialize the application are there. The server.start line initializes a server object with the new connection selected. That means you could maintain several open connections at the same time, as shown in Listing 5-3.

After executing the code from Listing 5-2, you get the following line:

Server running at: http://localhost:8000

And if you try to browse to http://localhost:8000, all you’ll get is the response from Figure 5-1, which is absolutely normal, because even though you’ve created a web server, you haven’t registered any routes yet.

'use strict';

const Hapi=require('hapi');

// Create a server with a host and port

const server=Hapi.server({

    host:'localhost',

    port:8000

});

const adminServer = Hapi.server({

        host: 'localhost',

        port: 8001

});

// Add a route to list users

adminServer.route({

    method:'GET',

    path:'/users',

    handler:function(request,h) {

        //your code here

    }

});

// Start the server

async function start() {

    try {

        await server.start();

        await adminServer.start();

    }

    catch (err) {

        console.log(err);

        process.exit(1);

    }

    console.log('Servers running at: ', server.info.uri, ' and ', adminServer.info.uri);

}

start()

Listing 5-3

Example of Two Different Servers Being Started on Different Ports

This code initializes the application , which in turn sets up two different servers: one for the API itself and another one for an admin system. In this code you can also see how easy it is to set up routes with HAPI. Although the code can clearly be cleaned up and the routes definitions can be taken out to a separate file, this is a great example of how two (or more!) servers with their respective routes can be configured using this framework.

Another interesting bit that HAPI provides is the route templates you can use by setting up your own. With it, you can use named parameters as seen in Listing 5-4.

'use strict'

const Hapi = require('hapi');

const server = new Hapi.Server({

        host: 'localhost',

        port: 3000

});

const getAuthor = (request, reply) => {

    // here the author and book parameters are inside

    // request.params

};

server.route({

    path: '/{author}/{book?}',

    method: 'GET',

    handler: getAuthor

});

Listing 5-4

Setting Up Routes with URL Templating in HAPI.JS

In the code from Listing 5-4, when setting up the route, anything that’s inside curly brackets is considered a named parameter. The last parameter though, has a ? added to it, which means it’s optional.

Note

Only the last named parameter can be set as optional; otherwise, it makes no sense.

In addition to the ?, you can use another special character to tell HAPI the number of segments a named parameter should match; that character is the * and it should be followed by a number greater than 1, or nothing, if you want it to match any number of segments.

Note

Just like the ? character, only the last parameter can be configured to match any number of segments.

Listing 5-5 shows some examples.

server.route({

    path: '/person/{name*2}',   // Matches '/person/john/doe'

    method: 'GET',

    handler: getPerson

});

server.route({

    path: '/author/{name*}',   // Matches '/author/j/k/rowling' or '/author/frank/herbert' or /author/

    method: 'GET',

    handler: getAuthor

});

function getAuthor(req, reply) {

   // The different segments can be obtained like this:

  let segments = req.params.name.split('/')

  //the rest of your code goes here...

}

function getPerson(req, reply) {

  let segments = req.params.name.split(''/')

  //the rest of your code here...

}

Listing 5-5

Multid-Segment Parameters Example

Express.js

This is one of the most common and used frameworks for Node. As you’re about to see, it provides all the required building blocks for creating both web apps, and microservices. Table 5-3 shows more details about this framework.

Table 5-3

Express.js Module Information

Category	Request/Response handler, Routes handler, Middleware
Current version	4.16.3
Description	Express is a full-fledged web framework providing small and robust tools for HTTP servers, making it a great candidate for all kinds of web applications, including RESTful APIs.
Home page URL	http://expressjs.com
Installation	$ npm install express

Code Examples

Express.js is sometimes considered the de facto solution when it comes to building a web application in Node.js, much like Ruby on Rails was for Ruby for a long time.

That being said, it doesn’t mean Express.js should be the only choice or that it is right choice for every project; so make sure that you are well-informed before choosing a web framework for your project.

This particular framework has evolved over the years, and now in version 4 it provides a generator. To initialize the entire project, you first have to install it with the following line:

$ npm install express-generator -g

After the installation is complete, you can use the following line:

$ express ./express-test

This line will generate an output like the one shown in Figure 5-2.

The framework generates a lot of folders and files, but in general, it’s the structure for a generic web application, one that has views, styles, JavaScript files, and other web app–related resources. This is not for us since we’re building a RESTful API. You’ll want to remove those folders (views and public, more specifically).

To finalize the process, just enter the folder and install the dependencies; this will leave you with a working web application. Check Listing 5-6 if you’re curious about what it takes to initialize the framework (this is all created by Express as part of the init command).

var express = require('express');

var path = require('path');

var favicon = require('serve-favicon');

var logger = require('morgan');

var cookieParser = require('cookie-parser');

var bodyParser = require('body-parser');

var index = require('./routes/index');

var users = require('./routes/users');

var app = express();

// view engine setup

app.set('views', path.join(__dirname, 'views'));

app.set('view engine', 'jade');

// uncomment after placing your favicon in /public

//app.use(favicon(path.join(__dirname, 'public', 'favicon.ico')));

app.use(logger('dev'));

app.use(bodyParser.json());

app.use(bodyParser.urlencoded({ extended: false }));

app.use(cookieParser());

app.use(express.static(path.join(__dirname, 'public')));

app.use('/', index);

app.use('/users', users);

// catch 404 and forward to error handler

app.use(function(req, res, next) {

  var err = new Error('Not Found');

  err.status = 404;

  next(err);

});

// error handler

app.use(function(err, req, res, next) {

  // set locals, only providing error in development

  res.locals.message = err.message;

  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page

  res.status(err.status || 500);

     res.render('error');

});

module.exports = app;

Listing 5-6

Content of the app.js File Generated by Express

Let’s now take a look at Listing 5-7 and what it takes to set up a route in Express.js.

const express = require("express");

const app = express()

//...

app.get('/', (req, res)  => {

  console.log("Hello world!")

})

Listing 5-7

All That’s Needed Is Just a Few Lines of Code

That’s it. All that you need to remember when setting up a route is the following: app.VERB(URL-TEMPLATE, HANDLER-FUNCTION). The handler function will receive three parameters: the request object, the response object, and the next function. The last parameter is only useful when you set up more than one handler for the same route and method combination; that way you can chain the methods like they are middleware.

Take a look at the following example in Listing 5-8:

app.route('/users/:id')

   .all(checkAuthentication)

   .all(loadUSerData)

   .get(returnDataHandler)

   .put(updateUserHandler)

Listing 5-8

Chaining Verbs to the Same URI

In the preceding code, there are several interesting things happening:

• A named parameter is used for the ID of the user.

• Two middleware functions are set up for every verb hitting the '/users/:id' route.

• It’s setting up a handler for the GET method hitting the URL, and at the same time, it’s setting up a handler for when the verb is PUT—all in the same line of code.

Express provides its own flavor of named parameters (you saw an example of that in the preceding code), but there are other things you can do. For instance, you can use regular expressions .

The code from Listing 5-9 matches both '/commit/5bc2ab' and '/commit/5bc2ab..57ba31', and you can see that getting the parameter inside the handler’s code is simple too.

You can also set a callback function to do some processing when a specific named parameter is received (as seen in Listing 5-10); for instance:

router.get(/^\/commit\/(\w+)(?:\.\.(\w+))?$/, (req, res) => {

  let from = req.params[0];

  let  to = req.params[1] || 'HEAD';

  res.send('commit range ' + from + '..' + to);

});

Listing 5-9

Example Showing the Use of Regular Expressions to Define a Route

const router = express.Router()

const express = require('express')

const app = express()

router.param('user_id', (req, res, next, id) => {

   loadUser(id, function(err, usr) {

      if(err) {

         next(new Error("There was an error loading the user's information")) //this will call erorr handler

      } else {

         req.user = usr

         next()

      }

   })

})

//then on the route definition

app.get('/users/:user_id', (req, res) => {

    //req.user is already defined and can be used

})

Listing 5-10

Cleaner Code Using Parameter-Specific Callbacks

If there is an error on the user_id callback function , then the route’s handler will never be called, because the first error handler will be called instead.

Finally, let’s look at some examples of middleware usage inside Express.js. I already covered the basics for this type of function earlier, but you never saw how to use it with Express.js.

You can do it in two ways: set up a global middleware (Listing 5-11) or a route-specific middleware (Listing 5-12).

For a global middleware, you just do this:

app.use((req, res, next) => {

   //your code here will be executed on every request

   next() //remember to call next unless you want the chain to end here.

})

Listing 5-11

Middleware Example

For a route-specific middleware, you do this:

app.use('/books', (req, res, next) => {

        //this function will only be called on this path

        next() //always important to call next unless you don't want the process' flow to continue.

})

Listing 5-12

Route-Specific Middleware Syntax

You can even set up a route-specific stack of middleware , as seen in Listing 5-13.

app.use('/books', function(req, res, next){

    //this function will only be called on this path

    next() //always important to call next unless you don't want the process' flow to continue.

}, function(req, res, next) {

    //as long as you keep calling next, the framework will keep advancing in the chain until reaching the actual handler

     next()

})

Listing 5-13

Example of a Stack of Middleware for a Specific Store

Vatican.js

Vatican.js is an attempt at creating an easy-to-use and boilerplate-based library, which can reduce the coding time while working on RESTful APIs. When you’re starting to work on your API’s code, there are a lot of repeated tasks that you need to perform over and over, until you have all your endpoints set up, and your models, and so on. This library attempts to remove all that work by generating most of it automatically. Table 5-7 shows more details about the framework.

Table 5-7

Vatican.js Module Information

Category	Request/Response handler, Middleware, Routes handling
Current version	1.5.0
Description	Vatican.js is another attempt of a framework designed to create RESTful APIs. It doesn’t follow the Express/Restify path. Its focus is more on the MVP stage of the API, but it provides an interesting alternative.
Home page URL	https://github.com/deleteman/vatican
Installation	$ npm install –g vatican

Code Examples

After installation, Vatican.js provides a command-line script to create the project and add resources and resource handlers to it. So to get the project started, you’ll need to use the following command:

$ vatican new test_project

The preceding code generates the output shown in Figure 5-3.

The main file (index.js) has the content in Listing 5-19.

var Vatican = require("vatican")

//Use all default settings

var app = new Vatican()

app.dbStart(function() {

    console.log("Db connection stablished...")

    //Start the server

    app.start()

} )

Listing 5-19

Default index.js Generated by Vatican.js.

Vatican comes with MongoDB integration , so the dbStart method is actually a reference to the connection to the NoSQL storage. By default, the server is assumed to be in localhost and the database name used is vatican-project.

The default port for Vatican is 8753, but just like all defaults in Vatican, it can be overwritten during the instantiation stage. These are the options that can be passed in to the constructor, as shown in Table 5-8.

Table 5-8

List of Options for the Vatican.js Constructor

Option	Description
port	Port of the HTTP server
handlers	Path to the folder where all handlers are stored. By default it’s ./handlers
db	Object with two attributes: host and dbname
cors	This is either a Boolean indicating whether CORS is supported by the API or an object indicating each of the supported headers.

Setting up a route in Vatican is also a bit different than the others; the command-line script provides the ability to autogenerate the code for the entity/model file and the controller/handler file, which also includes basic code for the CRUD operations.

To autogenerate the code, use the following command from within the project’s folder:

$ vatican g Books -a title:string description:string copies:int -m newBook:post listBooks:get removeBook:delete

This line outputs something like what’s shown in Figure 5-4.

It basically means that Vatican created both the handler file and the entity (inside the schemas folder). If you check the handler’s file, you’ll notice how all the actions already have their code in there; that’s because Vatican was able to guess the meaning of the actions provided in the command line by using their name.

• newBook: Using “new” assumes you’re creating a new instance of the resource.

• listBooks: Using “list” assumes you want to generate a list of items.

• removeBook: Using “remove” assumes you’re trying to remove a resource.

Variations of those words are also valid, and Vatican will use them to guess the code. You can now go ahead and start the server; the endpoints will work and save information to the database.

One final comment on resource generation is about routing; you haven’t specified any routes yet, but Vatican has created them anyway. Inside the handler file, you’ll notice annotations as shown in Listing 5-20.

module.exports = class BooksHdlr {

        constructor(model, dbModels) {

                this.model = model;

                this.dbModels = dbModels;

        }

        @endpoint (url: /books method: post)

        newBook(req, res, next) {

                var data = req.params.body

                //...maybe do validation here?

                this.model.create(data, function(err, obj) {

                        if(err) return next(err)

                        res.send(obj)

                })

        }

        @endpoint (url: /books method: get)

        listBooks(req, res, next) {

                var page = null,

                        size = null

                if(req.params.query.page || req.params.query.size) {

                        page = req.params.query.page || 0

                        size = req.params.query.size || 10

                }

                var query = {}

                var finder = this.model.find(query)

                if(page !== null && size !== null) {

                        finder

                                .skip(page * size)

                                .limit(size)

                }

                finder.exec(function(err, list) {

                        if(err) return next(err)

                        res.send(list)

                })

        }

        @endpoint (url: /books method: delete)

        removeBook(req, res, next) {

                var id = req.params.query.id || req.params.url.id || req.params.body.id

                this.model.remove({_id: id}, function(err) {

                        if(err) return next(err)

                        res.send({success: true})

                });

        }

}

Listing 5-20

Generated Code for New REST Methods with Endpoint Definition Included

The annotations in the preceding example on the method’s definition are not standard JavaScript, but Vatican is able to parse them and turn them into data during boot up. That means that with Vatican there is no routes file; each route is defined above its associated method, and if you want to get a full list of routes for your system, you can use the following command line:

$ vatican list

And it’ll produce the output shown in Figure 5-5, which lists for every handler all the routes with the method, the path, the file, and the associated method name.

Note

The annotations can be commented out with a single line comment (//) to avoid your editor/linter from complaining about the construct; even then, Vatican.js will be able to parse it.

Finally, Vatican also fits inside the middleware category, and that’s because even though it’s not based on Connect or Express, it does support Connect-based middleware. The only difference is the method name that uses it.

vatican.preprocess(middlewareFunction) //generic middleware for all routes

vatican.preprocess(middelwareFunction, ['login', 'authentication']) //middleware for two routes: login and authentication.

Listing 5-21

Middleware Usage Example

To set the name of a route, you can add that parameter in the annotation, like in Listing 5-22.

@endpoint(url: /path method: get name: login)

Listing 5-22

Setting Up Named Routes Using Annotations

There are still some more features that Vatican.js provides. To read about them, please refer to the official web site.

swagger-node-express

This module bridges the gap between Swagger and Express, allowing you to auto-document your express APIs easily. Table 5-9 shows more details about it.

Table 5-9

swagger-node-express Module Information

Category	Up-to-date documentation
Current version	2.1.3
Description	This is a module for Express. It integrates into an Express app and provides the functionalities that Swagger3 does for documenting APIs, which is a web interface with documentation of each method and the ability to try these methods.
Home page URL	https://github.com/swagger-api/swagger-node
Installation	$ npm install swagger-node-express

Code Examples

The first thing you need to do after you install the module is integrate Swagger into your Express app. Listing 5-23 provides the code to do that.

// Load module dependencies.

const express = require("express")

, app = express()

, bodyParser = require("body-parser")

, swagger = require("swagger-node-express").createNew(app);

// Create the application.

app.use(express.json());

app.use(bodyParser.urlencoded({extended: true}));

Listing 5-23

First Steps After Installing swagger-node-express

After integration is done, the next thing to do is add the models and the handlers. The models are in the form of JSON data (where this is defined is left to the preference of the developer). The handlers contain the actual code of the route handlers, along with other descriptive fields that act as documentation.

Listing 5-24 is an example of a model definition.

exports.models = {

        "Book": {

                "id": "Book",

                "required": ["title", "isbn"],

                "properties": {

                        "title": {

                                "type": "string",

                                "description": "The title of the book"

                        },

                        "isbn": {

                                "type": "string",

                                "description": "International Standard Book Number"

                        },

                        "copies": {

                                "type": "integer",

                                "format": "int64",

                                "description": "Number of copies of the book owned by the bookstore"

                        }

                }

        }

}

Listing 5-24

Model Definition Using Simple JSON Format

In Listing 5-24, the format used is JSON Schema⁴ and it might be tedious to maintain, but it provides a standard way for Swagger to understand how our models are created.

Tip

Manually maintaining a lot of model descriptions might be too much work, and it’s prone to generate errors in the documentation, so it might be a good idea to either use the description to autogenerate the code of the model or autogenerate the description from the model’s code.

Once the model description is done, you add it to Swagger, as deomstrated in Listing 5-25.

// Load module dependencies.

const express = require("express")

, swagger = require("swagger-node-express")

, models = require('./models-definitions').models

//....

swagger.addModels(models)

Listing 5-25

Letting Swagger Know About Your Models

Now you move on to the handler’s description, which contains fields describing each method, and the actual code to execute.

const swagger = require("swagger-node-express");

//Book handler's file

exports.listBooks = {

        "spec": {

                "description": "Returns the list of books",

                "path": "/books.{format}",

                "method": "GET",

                "type": "Book",

                "nickname": "listBooks",

                "produces": ["application/json"],

                "parameters": [swagger.paramTypes.query("sortBy","Sort books by title or isbn", "string")]

        },

        "action": (req, res) => {

                //...

        }

}

//main file's code

var bookHandler = require("./bookHandler")

//...

swagger.addGet(bookHandler.listBooks) // adds the handler for the list action and the actual action itself

Listing 5-26

Handler’s Code and Documentation Definition and Setup

This code shows how to describe a specific service (a list of books). Again, some of these parameters (inside the spec object) can be autogenerated; otherwise, manually maintaining a lot of specs can lead to outdated documentation.

Finally, set up the URLs for the Swagger UI (which will display the documentation and will also provide the UI to test the API) and the version, as shown in Listing 5-27.

swagger.configure("http://myserver.com", "0.1")

Listing 5-27

Letting Swagger Know Its UI’s URL

Let’s now look at Listing 5-28, a complete example of a main file, showing the setup and configuration of Swagger and the Swagger UI.⁵

// Load module dependencies.

const express = require("express")

, models = require("./models-definitions").models

, app = express()

, bodyParser = require("body-parser")

, booksHandler = require("./booksHandler") //load the handler's definition

, swagger = require("swagger-node-express").createNew(app) //bundle the app to swagger

// Create the application.

app.use(express.json());

app.use(bodyParser.urlencoded({extended: true}));

var static_url = express.static(__dirname + '/swagger-ui') //the swagger-ui is inside the "swagger-ui" folder

swagger.configureSwaggerPaths("", "api-docs", "") //you remove the {format} part of the paths, to simplify things

app.get(/^\/docs(\/.*)?$/ ,  (req, res, next) => {

    if(req.url === '/docs') {

        res.writeHead(302, {location: req.url + "/"})

        res.end()

        return

    }

    req.url = req.url.substr('/docs'.length)

    return static_url(req, res, next)

})

//add the models and the handler

swagger

    .addModels(models)

    .addGet(booksHandler.listBooks)

swagger.configure("http://localhost:3000", "1.0.0")

app.listen("3000")

Listing 5-28

Full Example of Swagger-Express Integration

Note

Before trying out this code, you’ll have to copy the folder called “swagger-ui” inside the module’s folder, into your project’s root folder (or whatever you set the static_url variable to).

Figure 5-6 is a screenshot of the resulting UI that you get by visiting http://localhost:3000/docs.

I/ODocs

Another option when it comes to self-documenting APIs is I/O Docs, which, although in the end provides similar results to Swagger, also offers quite a different approach getting there.

Table 5-10 shows the details on this particular project, as well as the steps required to install it.

Table 5-10

I/O Docs Module Information

Category	Up-to-date documentation
Current Version	N/A
Description	I/O Docs is a live documentation system designed for RESTful APIs. By defining the API using the JSON Schema, I/O Docs generates a web interface to try out the API.
Home page URL	https://github.com/mashery/iodocs
Installation	$ git clone http://github.com/mashery/iodocs.git $ cd iodocs $ npm install

Code Examples

After installation is done, the only thing left to do to test the application is create a configuration file; there is a config.json.sample file you can use as a starting point.

Tip

You can copy the config.json.sample file using the cp command like so: cp config.json.sample config.json . By doing that, you immediately have a valid config file to start using.

To start up the documentation server , you’ll first need to start your redis server and then use one of the following commands:

$ redis-server #preferabliy you'll do this in another console, since this is a blocking operation

$ npm start       #for *nix and OSX systems

C:\your-project-folder> npm startwin        #for Windows systems

After that, use your browser to go to http://localhost:3000 to start testing the documentation system.

Tip

If you get a login modal the first time you visit that URL, just hit ENTER (with empty credentials) and you’ll be logged in.

Figure 5-7 is a screenshot of one of the sample APIs already configured .

As you can see in Figure 5-7, when the methods are tested, a response is shown underneath. If you want to set up your own API, there are a few things to do:

1. 1.

   Add your API to the list of documented APIs inside public/data/apiconfig.json like in Listing 5-29.

   {

       "klout": {

           "name": "Klout v2 API"

       },

       "egnyte": {

           "name": "Egnyte API"

       },

       "usatoday": {

           "name": "USA TODAY Census API"

       },

       "foursquare": {

           "name": "Foursquare (OAuth 2.0 Auth Code)"

       },

       "rdio": {

           "name": "Rdio Beta (OAuth 2.0 Client Credentials)"

       },

       "rdio2": {

           "name": "Rdio Beta (OAuth 2.0 Implicit Grant)"

       },

       "requestbin": {

           "name": "Requestb.in"

       },

       "bookstore": {

           "name": "Dummy Bookstore API"

       }

   }

   Listing 5-29

   Adding Your API’s Entry to the List of Docummented APIs

    
2. 2.

   Create a new file called bookstore.json and store it inside the public/data folder. This new JSON file will contain the description of your API and the methods in it; something like shown in Listing 5-30.

   {

       "name": "Dummy Bookstore API",

       "description": "Simple bookstore API",

       "protocol": "rest",

       "basePath": "http://api.mybookstore.com",

       "publicPath": "/v1",

       "auth": {

           "key": {

               "param": "key"

           }

       },

       "headers": {

           "Accept": "application/json",

           "Foo": "bar"

       },

       "resources": {

           "Books": {

               "methods": {

                   "listBooks": {

                       "name": "List of books",

                       "path": "/books",

                       "httpMethod": "GET",

                       "description": "Returns the list of books in stock",

                       "parameters": {

                           "sortBy": {

                                   "type": "string",

                                   "required": false,

                                   "default": "title",

                                   "description": "Sort the results by title or ISBN code"

                           }

                       }

                   },

                   "showBook": {

                       "name": "Show book",

                       "path": "/books/{bookId}",

                       "httpMethod": "GET",

                       "description": "Returns the data of one specific book",

                       "parameters": {

                           "bookId": {

                                   "type": "string",

                                   "required": true,

                                   "default": "",

                                   "description": "The ID of the specific book"

                           }

                       }

                   }

               }

           }

       }

   }

   Listing 5-30

   The Full JSON Definition of Your API’s Endpoints

    
3. 3.
   Start up the documentation server and point your web browser to it. You’ll see a screen that looks similar to Figure 5-8.

   

    

Unlike with Swagger, this documentation system is not meant to be integrated into your project, so autogenerating the JSON code might be a bit more difficult. The server does, however, auto-adapt to updates on the JSON file, so you don’t have to restart it everytime to change something, but you would still have to find a way to easily generate that JSON definition and copy it into the right folder.

The Specifications

Now that we know the current situation of the chain and the goal of our system, we need to start writing some hard specs. These will determine the way the system evolves and help with planning the development by giving us a better idea of the size of the project. Specifications also help us spot any design errors before we start with the implementation.

Table 6-2 gives us a pretty good idea of the size of the project; with it we’re able to estimate the amount of work that we have ahead of us.

There is one more aspect to discuss because it isn’t covered in the resources in Table 6-1 or with the endpoints/authentication in Table 6-2.

The authentication scheme will be simple. As discussed in Chapter 2, we’ll use the stateless alternative by signing every request with a MAC (message authentication code). The server will re-create that code to verify that the request is actually valid. This means there will not be a signing process embedded into our system; that can be done by the client. No need to worry about that for now.

UML Diagram

With the level of specification we have so far, we could very well skip this step and jump right into the next one; but for the sake of completeness and getting a clear idea across, let’s create a basic UML diagram to provide another way to show how all of the resources of the API will relate to each other.

As you can see in Figure 6-3, most of the diagram consists of groups of aggregations between different resources. The store has a group for employees, a group for books, a group for the books’ authors (usually it’s one author per book, but there are books that are co-authored by two or more authors), and a group for client reviews.

Choosing the Right Modules for the Job

This is the last step of our preparation process . Now that you know the problem to solve and you have a pretty well-defined specification of how to handle the development, the only thing left to do, aside from actually coding, is to pick the right modules.

Simplification of the Store–Employee Relationship

When I listed every resource, I said that the store would keep a list of employees and that each employee would keep a direct reference to the store. To maintain those relationships in MongoDB, however, means extra work. And since we don’t really need this, we’ll just keep the employees’ records unaware of their assigned store and make sure that each store keeps up with the employees working in it.

Adding Swagger UI

I talked about Swagger back in Chapter 5, and I briefly mentioned Swagger UI, but I never really explained a lot. The Swagger UI project is the UI we’ll use to test our API. The swagger-node-express and swagger-node-restify modules provide the back-end infrastructure that the UI needs; but without the Swagger UI project, we have nothing.

So, just download version 2.1.5 of this project from https://github.com/swagger-api/swagger-ui/tree/v2.1.5 and add its dist folder into your project’s root. I’ll go over how to configure it in a bit.

Simplified Security

To simplify the security, we’ll work under the premise that we’re not really making a public API but rather an API for clients that are directly under our control.

That means that we will not require every client to request an access token with a limited life span. Instead, we’ll work under the assumption that when we set up a new client on a new branch, we share the secret passphrase, so the clients will always send the MAC code encrypted using this passphrase, and the API will re-hash each request to make sure both results match. This way we’re still validating the requests and we’ll still remain true to REST, because this method is stateless. We’re just simplifying the addition of new client applications.

Upon receiving the request, the API will grab the data from the header and encrypt it again using the correct passphrase. If the result is the same as the value of the api_key parameter, then it’ll dim the request as authentic. Otherwise, it’ll reject the request with a 401 error code.

A Small Backdoor for Swagger

The other change that we’re making is because the Swagger UI has no de facto support for our authentication scheme. We can send a fixed api_key parameter, but we would have to change the code of the client to get it to use the same algorithm we’re using.

This is why we’ve added a small backdoor in our code, to let the Swagger -UI go by without needing to authenticate each request.

The hack is very simple. Since the UI can send a fixed api_key, then we’ll let all requests that have an api_key equal to 777 pass, automatically trusting them.

This backdoor will need to be removed when going into production to avoid any security issues, of course.

Once this has been added, you can visit http://localhost:9000/swagger-ui to check out the UI.

MVC

In Chapter 4, I went over several variations of the MVC pattern, but never actually settled on one to be used on our API. Personally, I really liked the idea behind Hierarchical MVC, since it allows for some really clean code.

That said, it also means extra work when developing, and considering that there aren’t many cases where in one controller we’re dealing with resources from another, we’ll just try to keep it simple and go with a basic MVC.

config

Controllers

This file (Listing 7-2) is used to export each controller. Using this technique, we can import the entire folder like if it was a module, like this:

Every controller extends this class (Listing 7-3), gaining access to the methods shown earlier. We’ll use basic prototypical inheritance, as you’ll see in a bit when we start listing the other controllers’ code.