Designing for RPC

Designing for RPC involves deciding which method calls will be RPCs across the network. Apart from that, your code will mostly look the same as it did running on a single machine. Figure 13.1 shows the new design for the current scenario. Note how it replaces methods between two bounded contexts with RPCs across the network.

In the (fictitious) current system, the Discovery bounded context is calling FindUsersFollowers() on the FollowerDirectory class, which belongs to the Account Management bounded context. This is a binary dependency that requires in-process communication. You can see the code demonstrating this in Listing 13-1.

Listing 13-1 shows the FollowerDirectory.FindUsersFollowers() method being called. This is the problematic method that couples two bounded contexts. It is going to be replaced with a similarly named RPC across the network, thereby removing the problematic binary dependency between the Discovery and Account Management bounded contexts.

Figure 13.1 also provides further background for the use case you are going to implement. You can see that the use case is triggered when a user logs in and arrives at her home page. When this happens, the business requirement is for users to see a list of recommended users whom they might want to follow. This is important to the business because it allows users to discover other users and hot topics so they continue to return to the site. An entire team of business people and developers is focused on helping users discover content. The team is known as the Discovery team, and the Discovery bounded context represents its area of the domain.

Implementing RPC over HTTP with WCF and SOAP

Integrating two bounded contexts using SOAP can initially be quite fast and relatively easy when using .NET’s Windows Communication Foundation (WCF). You’ll see this firsthand as you start to implement the use case shown in Figure 13.1 in the following sections.

Creating a WCF Service

To get started, you need to create a blank Visual Studio solution that will be home to all the bounded contexts (in this SOAP example). You can call this solution PPPDDD.SOAP.SocialMedia. The first bounded context to be created is Account Management. To add the Account Management bounded context, you need to add a new WCF Service Application to the project called AccountManagement, as shown in Figure 13.2.

In the old monolithic application, as you saw in Listing 13-1, there was a class called FollowerDirectory that had a method called FindUsersFollowers. To turn this into an RPC call, you can simply add a WCF Service to the root of the project called FollowerDirectory. Then you can use WCF Service contracts to declare your RPCs, as shown in the next section.

Service Contracts

After you’ve added the WCF Service, two files are added to the root of the project: FollowerDirectory.svc.cs and IFollowerDirectory.cs. The latter is what Visual Studio uses to generate a public SOAP contract (using the Web Service Description Language, or WSDL). The former is the implementation; your custom code goes in it and is run when RPC calls are made at run time. You see this in action shortly, so don’t worry if it doesn’t make perfect sense.

WCF has two annotations: ServiceContract and OperationContract. ServiceContract is added to an interface to signify that the class contains methods that can be called as RPCs across the network. OperationContract then signifies which methods on an interface decorated with ServiceContract are the RPCs. Therefore, to create the FollowerDirectory.FindUsersFollowers() RPC call, you should apply those two attributes, as shown in Listing 13-2.

Listing 13-2 is all that Visual Studio and WCF requires from you to be able to generate the RPC infrastructure. You’ll see later that Visual Studio automatically generates proxies of these classes on clients of the web service. This “networking for free” is what makes WCF and SOAP so appealing to many.

Before your service will work, you need to provide an implementation in the FollowerDirectory.svc.cs file. You can see a basic implementation in Listing 13-3 that generates a few dummy Followers in-memory and returns them. You can update your FollowerDirectory with this implementation.

Testing WCF Services

You’re now in a position to test that you really can call FindUsersFollowers()over the network as an RPC. Visual Studio makes this easy with the test client it provides. To run the test client, highlight the FollowerDirectory.svc item in the Solution Explorer (not FollowerDirectory.sv.cs) and press F5. You will then see the test client as illustrated in Figure 13.3.

To test your new service, just double-click its name (FindUsersFollowers) in the left-hand Explorer pane, and then enter a value in the Value column for the row accountId in the right pane. After doing that, if you click the Invoke button, your FindUsersFollowers RPC will be carried out over the network, and the results will be displayed in the lower half of the right pane, as shown in Figure 13.4.

If you want to see how the data was transmitted across the network, you can click on the XML tab at the bottom of the right pane. By doing that, you see the raw SOAP:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header />
  <s:Body>
    <FindUsersFollowersResponse>
      <FindUsersFollowersResult
xmlns:a="http://schemas.datacontract.org/2004/07/
AccountManagement" xmlns:i="http://www.w3.org/2001/
XMLSchema-instance">
        <a:Follower>
          <a:FollowerId>follower_0</a:FollowerId>
          <a:FollowerName>happy follower 0</a:FollowerName>
          <a:SocialTags
xmlns:b="http://schemas.microsoft.com/2003/10/
Serialization/Arrays">
            <b:string>programming</b:string>
            <b:string>DDD</b:string>
            <b:string>Psychology</b:string>
          </a:SocialTags>
        </a:Follower>
        <a:Follower>
        ...

Creating WCF Service Clients

You’re now about to see that the WCF, SOAP, and Visual Studio combination does a lot of the hard work for you. You’ll first create the Discovery bounded context project, and you’ll then see how you can start making RPC calls to the Account Management bounded context just by pointing the Discovery bounded context to the uniform resource locator (URL) of the Account Management bounded context.

To begin, you need to add a new WCF Service Application to the solution called Discovery that represents the Discovery bounded context. Inside the Discovery bounded context, you then need to add a WCF Service called Recommender. Recommender provides the web services that the website uses to get the list of recommended users. You may find it helpful to quickly refer to the design in Figure 13.1.

Recommender has two responsibilities. First, it provides the API for clients to request recommendations. To fulfill that responsibility, it makes the RPC to the Account Management bounded context get an Account’s followers. To implement that, you need to have the Account Management project running. (Highlight it in the Solution Explorer and press Ctrl+F5.) You can then test that it is running by directly accessing it in a web browser at http://localhost:3100/FollowerDirectory.svc. If the page has the heading “FollowerDirectory Service,” things are working.

Next, you need to pass the URL to Visual Studio so it can generate the proxy classes. If you right-click on the References node for the Discovery project in the Solution Explorer and select Add Service Reference, the URL can be pasted into the Address field. All that’s left is to change the Namespace (at the bottom of the Add Service Reference dialog) to AccountManagement and click Go. Your screen should then resemble Figure 13.5, which shows the expanded FollowerDirectory node revealing the web service it has identified. Once you’re happy, you can click OK.

To see the generated proxy classes, you can inspect the AccountManagement item that was added to the Service References folder. Figure 13.6 shows the generated proxy classes. These are the classes that you will shortly instantiate in the Discovery bounded context and call methods on to invoke RPCs across to the Account Management bounded context (via SOAP/HTTP).

The last step is to build the Recommender web service that puts the generated proxy classes to work. Listing 13-4 and Listing 13-5 show a basic implementation of the IRecommender and Recommender that do just enough to demonstrate the RPC call. You need to add these to your Discovery project.

In Listing 13-5, an instance of AccountManagement.FollowerDirectoryClient is created. It is a proxy class that Visual Studio generated when adding the Service Reference. When its FindUsersFollowers() method is called, it fires an RPC across the network and calls into the code you added in the Account Management bounded context. The main takeaway here is that WCF and Visual Studio took care of all the network-related plumbing. Most of the code you added would look very similar even if there was no network involved.

You can test that everything is successfully working by setting both projects to start up (as shown in the previous chapter by right-clicking the solution in the Solution Explorer and choosing Set Startup Projects) and then pressing F5 on the Recommender.svc in the Solution Explorer. The WCF test client pops up again, and this time you need to invoke GetRecommendedUsers(), as demonstrated in Figure 13.7.

The result of the RPC call in Figure 13.7 is the hard-coded data that is returned by the web service you created. This indicates that the RPC call between the two bounded contexts successfully occurred. Conclusively, this example’s aim of integrating the Account Management and Discovery bounded contexts without a binary dependency has now been achieved.

SOAP’s Decline

Although there are many existing public SOAP APIs, new APIs just aren’t being built with SOAP anymore. One of SOAP’s big pain points is the complexity and verbosity of its message format, which you saw a glimpse of earlier. People are critical of needless complexity, and they often cite SOAP as a perfect example of unnecessary complexity. Accordingly, you should be careful about exposing public SOAP APIs, but you shouldn’t feel too concerned about using SOAP internally if it suits your needs.

The modern preference for RPC over HTTP is to use lightweight, plain XML or JSON payloads. The next section shows examples of this using ASP.NET Web API.

Implementing RPC over HTTP with JSON Using ASP.NET Web API

The ASP.NET Web API is Microsoft’s latest framework for creating web services. Later you will see how it can be a good choice for building RESTful APIs. But for now you’ll see how it can make life easy when building JSON RPC APIs. As a starting point, you need a new blank Visual Studio solution called PPPDDD.JSON.SocialMedia. This solution needs to be populated with an ASP.NET Web Application project called AccountManagement. As you go through the creation process for the project, you need to select the Empty template and check the Web API check box. Once it’s created, you need to configure the project to always start on port 3200.

Controllers contain the code that will be run when web requests are made to your Web API. You can see controllers as an opportunity to express domain concepts from the ubiquitous language (UL), although you should be careful about putting domain logic in them. Some developers conceptualize controllers as Application Services.

To start with this example, you need to add a class called FollowerDirectoryController to the Controllers folder in the root of the project; Web API requires that controllers be placed in this folder. The code for FollowerDirectoryController is shown in Listing 13-6.

For demonstrative purposes, the FollowerDirectoryController in Listing 13-6 returns a list of hard-coded Followers (as JSON). In a real application, this class would likely perform database lookups or API calls to get the required follower information.

After starting the application (by pressing F5), you can test the new web service by hitting it in the browser. Using Web API’s default conventions, it is accessible at http://localhost:3200/api/followerdirectory/getusersfollowers?accountId=123, where the value for the accountId parameter is variable. (It can be anything in this example.) Figure 13.8 shows an example of hitting the API from a browser and viewing the JSON response.

You can see with this approach that you had to do a tiny bit of extra work setting up the controller compared to SOAP and WCF, but the data sent across the wire is so much cleaner and lighter that it’s easy to understand what is happening. This is also a bonus when it comes to debugging problems.

Lacking the richness of meta data provided by SOAP, it is not possible to automatically generate proxy classes for a plain JSON API. It still doesn’t have to be a lot of extra work, though, as you’ll now see.

To create a client of your JSON API, you need to add a new ASP.NET Web Application, called Discovery, to represent the Discovery bounded context. Inside the Discovery project, you need to add a class called RecommenderController in the Controllers folder. The code for this class is shown in Listing 13-7. For it to compile, you need to install HttpClient and ServiceStack.Text by running the following commands in the Nuget Package Manager Console:

Install-Package Microsoft.AspNet.WebApi.Client -Project Discovery
Install-Package ServiceStack.Text -Project Discovery

As Listing 13-7 shows, the logic for this implementation is similar to the WCF approach in the previous example. However, with this solution, you have to do the manual work of making the HTTP request and parsing the response yourself. As you can see, though, there are feature-rich libraries, provided by Microsoft and the community, that do a lot of the laborious work for you.

To test that everything works as intended, you need to set both projects as start-up projects (as shown in previous examples). You then need to navigate to the URL of the GetRecommendedUsers API you just created. The URL is http://localhost:{port}/api/recommender/getrecommendedusers?accountId=123 depending on which port the Discovery bounded context is using on your machine. A browser automatically pops up informing you of the port number when you press F5 inside the solution (or you can manually specify a port, as shown earlier in this chapter).

Verbs

HTTP provides a uniform interface for interacting with resources. For example, to fetch a resource, you send a GET request to its URI. To delete the same resource, you send a DELETE request to the URI. You can use PUT requests to create a resource at the desired URI. For adding items to a collection, you can use the POST verb. Examples of how these common verbs can be used to interact with resources are shown in Table 13.1.

By having a single set of verbs that are applied uniformly across the entire Internet, it is easy to build generic API clients and infrastructure components, such as caches, that understand the web’s conventions. Think about it—every programming language has libraries for working with HTTP. This is the power of common conventions, and you can also harness them when integrating bounded contexts.

Status Codes

Complementary to HTTP’s verbs are its status codes. As with verbs, having a common set of status codes means any agent on the web understands the conventions. For example, whenever you make a request to a URI that doesn’t exist, you get an HTTP 404 status code back because it is a common standard that almost all systems adhere to.

HTTP status codes are grouped by their first digit, as shown in Table 13.2. Within each group are more specific status codes.

Wikipedia has an accessible introduction to HTTP status codes if you would like to learn more (http://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

Headers

Aside from the URI and body of an HTTP request/response, you’re probably familiar with headers that provide extra information. RESTful systems frequently use HTTP’s caching headers that are covered later in this chapter.

Most RESTful applications require some level of security. Because a property of REST is statelessness, it’s often recommended that authentication and authorization details are communicated in headers using protocols such as OAuth.

For more information on headers that you can use in HTTP requests and responses, Wikipedia has an accessible, yet detailed entry (http://en.wikipedia.org/wiki/List_of_HTTP_header_fields).

DDD

Expressing business policies, using the UL, in a set of sketches is again a useful first step in designing a system. It nearly always makes sense to work out what problem you need to solve and what domain processes you need to model before you decide on a technical solution.

Figure 13.9 is a component diagram illustrating the new event-driven design of the Recommended Accounts use case. As with the messaging solution in the previous chapter, it focuses on domain commands and events. In fact, this design could be for a messaging system, because the diagram focuses on the flow of messages during the business use case and is independent of technology choices.

In Figure 13.9, you can see two key domain events. First, there is Began Following. Throughout the company, every member of staff understands that a Began Following domain event occurs when one account starts following another. This is part of the UL and one of the core concepts of the business. The other domain event shown is Premium Recommendations Identified. This is also part of the UL, representing occurrences where the Discovery bounded context has identified a premium account that a regular account may like to follow. This is a crucial domain concept, because promoting premium accounts to regular users is central to the new business model.

SOA

Chapter 11 showed you that following the principles of SOA can lead to loosely coupled bounded contexts. In turn, this can provide the platform for high-performing teams. SOA’s principles are technology agnostic, so you can apply them when building systems with HTTP.

By isolating bounded contexts each owned by a single team, loose coupling is within reach. Each team is free to develop its features in line with its business priorities, free of cross-team distractions or dependencies. All that changes when using SOA with HTTP compared to messaging is that the contract between teams is no longer classes in code, but the format of HTTP requests and responses. Upcoming examples fully demonstrate this.

Event-Driven and Reactive

You saw in Chapters 11 and 12 that asynchronous messaging, based on reactive principles, was the recommendation for building fault-tolerant scalable systems. This is also the case when integrating with REST and HTTP. As you are probably aware, HTTP doesn’t inherently support publish/subscribe, so there’s no way to push out events to subscribers as they occur like you can with a message bus. Instead, with REST, clients can poll for changes. Polling generally has negative connotations in terms of scaling, but utilization of HTTP’s caching conventions can negate this problem.

Figure 13.10 is the containers diagram for the new Reactive, RESTful social media system that will be built in the remainder of this chapter. Note how there are some similarities to a messaging system: each component is small so that it can be scaled independently according to business needs; bounded contexts do not share dependencies such as databases. Additionally, thanks to HTTP, each team can use any technologies it prefers within its bounded contexts (which was more difficult to achieve in the previous chapter). These traits support scalability, fault tolerance, and development velocity.

An important design consideration for scalability is the granularity of projects. For your HTTP APIs, you could put all your endpoints in one project, but then you couldn’t easily deploy them independently based on their individual scalability needs. The loose recommendation in this chapter is to start with one project per resource. Examples of this in Figure 13.10 are the stand-alone projects for the entry point resource and the Accounts resource.

When you have nested resources, you may also want to consider moving them into their own project sometimes. The main factors for doing so will usually be complexity of having extra projects traded off against the ability to scale APIs independently. You may even want to move individual request handlers into their own project if specific use cases have demanding scalability requirements.

HTTP & Hypermedia

Hypermedia is fundamental to REST because it is the factor that enables clients and servers to evolve independently of one another. So it can be useful to think a little about the hypermedia contracts up front before you start to build the system. (You can still iterate as you go along.) A good way to design REST workflows is to use sequence diagrams like the one shown in Figure 13.11 that demonstrates the event-driven Add Follower use case.

As you can see, clients are only coupled to the entry point URI. From there, they make requests to other services by following hypermedia links provided in responses. For instance, clients wanting to initiate the Add Follower use case (akin to a domain command) on the Account Management bounded context are only coupled to the URI of the entry point resource—/accountmanagement. From then on, clients merely follow links in the hypermedia, returned as HTTP responses, until the Followers resource is reached.

In the containers diagram shown in Figure 13.10, there is an indication next to each HTTP endpoint of its content type. Most of them show application/hal+json. HAL stands for Hypertext Application Language; it is essentially just well-known existing content types—XML and JSON—with conventions for representing hypermedia links. You can learn about the HAL standard in depth on Mike Kelly’s blog (http://stateless.co/hal_specification.html). The examples in the remainder of this chapter use application/hal+json, so you will still learn the basics just by reading this chapter.

Another content type shown on the containers diagram is application/atom+xml, which denotes Atom. Atom is a common standard for producing RSS feeds and thus is a great fit for representing lists of events. This is precisely how it is used by the Account Management bounded context—to represent the list of Began Following events that have occurred.

Using Atom as a feed of events is the main building block for building event-driven distributed systems with REST in this chapter. It doesn’t have to be Atom, but Atom’s popularity means you should definitely consider it.

An example of polling an Atom feed for domain events is shown in Figure 13.12. This diagram shows the flow of HTTP messages involved for polling the Began Following Atom feed that you will build later in this chapter.

Hypermedia-Driven APIs

Hypermedia is at the heart of REST. Accordingly, you will now see how to build hypermedia APIs in .NET with ASP.NET Web API. Although the implementation details will vary from framework to framework, the concepts are framework agnostic and will apply to any tools you may decide to build hypermedia APIs with.

As you’ve seen, the key benefit of hypermedia is that it decouples clients and servers, allowing independent evolution. But clients must know something up front about the API. This is the role of the entry point resource that clients should couple themselves to.

Entry Point Resource

When clients want to interact with a REST API, they start by requesting the entry point resource. From then on, they mostly just follow links in the hypermedia that is returned. Choosing where to locate your entry point(s) has a number of considerations that you should take into account. For instance, the design in Figure 13.10 chooses to have a single entry point per-bounded context. But you could have a single entry point for the entire system or go more fine-grained and have an entry point per top-level resource. Ultimately, you have to decide on a per-project basis how much of the system you want to expose via entry point resources.

Designing an entry point involves identifying the initial resources and transitions that should be available to consumers of the API. The Account Management bounded context’s entry point will be the list of top-level resources. In this example, that is just the Accounts resource. From the Accounts resource, hypermedia will link to individual accounts, and from individual accounts to details of those accounts, exposed as child resources, such as its followers. This is just repeating what you saw in the sequence diagram earlier in the chapter.

As you’re starting to see, links are the building blocks of hypermedia. But for API clients to follow links, they need to be able to decide which link provides the transition they are looking for. This is the role of link relations, which indicate what the link represents (or, more specifically, its relationship to the current resource). For example, for a resource that has many pages, to be hypermedia-compliant, it would need a link with the relation Next, which clients can follow to the next page. You’ll see a number of links and relations in the upcoming examples.

To build the API that produces the Account Management entry point, you need to start by adding a new ASP.NET application to the solution called AccountManagement.EntryPoint. This follows the convention of naming API projects based on the format {bounded context}.{Resource}. When adding the project to your solution, be sure to select the empty template, and be sure to check the Web API check box.

One decision still needs to be made before you can add the endpoint that produce the entry point resource. You need to choose a media type that supports hypermedia.

HAL

Traditionally, XHTML has been used as the hypermedia format for REST APIs. Unfortunately, it’s undesirable due to its verbosity (especially if you’re trying to escape from SOAP). Fortunately, though, a relatively new standard is available and gathering traction. This new standard is HAL, which was briefly introduced earlier in the chapter, and it comes in two main flavors: XML and JSON. Essentially, both of those well-known formats have been extended with specific conventions for representing links. This provides the hypermedia benefits of XHTML without the verbosity as the following example demonstrates.

{
  "_links": {
    "self": {
      "href":"http://localhost:4100/accountmanagement"
    },
    "accounts": {
      "href":"http://localhost:4101/accounts"
    },
 }
}

The entry point resource shown in the preceding snippet demonstrates the conventions for representing links in HAL (JSON). All links must be defined within an element at the root of the resource called _links. Each link begins with its relation (self and accounts in the example). Each link also contains an href, which is the URI of the resource it points to. Only the self link, which points to the current resource, is mandatory; all other links are optional.

To build the entry point resource API, you first need to configure the project to start on port 4100. (You can set this in the project’s properties on the Web tab.) You then need to configure a URI for the entry point by adding a route inside Web API’s WebAPIConfig, as shown in Listing 13-8. Your WebApiConfig file will be located in the App_Start folder that sits in the root of the project.

If you’re not familiar with Web API’s routing syntax, in Listing 13-8, the definition of the Entry Point route ensures that whenever a request comes in for the path /accountmanagement, the Get() method on a class called EntryPointController is invoked. Before you can implement that controller, you need to install a Nuget package that adds support for HAL in Web API. As you will see, this is an incredibly usable library that takes all the effort out of creating HAL APIs. To install WebApi.Hal into the AccountManagement.EntryPoint.Api project, you need to run the following command in the Nuget Package Manager Console:

Install-Package WebApi.Hal -Project AccountManagement.EntryPoint.Api

Once WebApi.Hal is installed, you need to tell Web API to make HAL (JSON) the default media type by updating your Global.asax.cs, as per Listing 13-9. This also sets HAL (XML) as the second preference. The two formatters, JsonHalMediaTypeFormatter and XmlHalMediaTypeFormatter, belong to the WebAPI.Hal package you just installed.

All dependencies are installed and configuration is now complete, paving the way for you to complete the Entry Point API by implementing the EntryPointController. You can achieve this by first adding a class called EntryPointController to the Controllers folder that sits at the root of the project. Once you’ve added the class, you can then replace the contents of the file with the code in Listing 13-10.

The code in Listing 13-10, when executed, will return the entry point resource as HAL-JSON (by default). This is because EntryPointRepresentation inherits from the Representation base class—a class that the WebApi.Hal library provides. When a class inheriting from Representation is returned from a controller method, the JsonHalMediaTypeFormatter will convert it to HAL-JSON.

Inside Get(), the code declaratively maps onto the response format. You can see two links are being generated in this code: Href and Links (a collection with just one link). These are the two links that will appear in the response. You can see all this in action by testing out what you have so far.

Testing HAL APIs with the HAL Browser

A huge benefit of building hypermedia APIs on top of common standards is that it is easy to create generic clients that can explore APIs built using those standards. One such tool for HAL is the Hal browser, a small web application that allows you to consume and interact with HAL APIs. You’ll now see how to use the HAL browser to test the Entry Point API you have just built.

To install the HAL browser, you have to download it (https://github.com/mikekelly/hal-browser/archive/master.zip) and then unzip it. Finally, you need to copy the contents of the unzipped folder into the root of your AccountManagement.EntryPoint.Api project’s folder in Windows Explorer. If you open Windows Explorer at the root of the AccountManagement.EntryPoint.Api project, there should be a file called browser.html. If you don’t see it, the file is in the wrong location.

If you are happy that the files are copied into the correct location, you can press F5 to run your project. In the browser that Visual Studio starts up for you, you can access the HAL browser by navigating to http://localhost:4100/browser.html. (This assumes that you configured this project to always use port 4100, as explained previously.) After navigating to browser.html, if everything is working correctly, you will see the HAL browser, as per Figure 13.13.

When you do access the HAL browser, you’ll notice it doesn’t show your entry point resource. This is because the HAL browser looks for API entry points at the default path (/). To remedy this, simply enter /accountmanagement into the HAL browser’s navigation bar (below the Explorer label) and click GO. You should then see the raw entry point resource (on the right side) and the interactive tools (on the left side), as shown in Figure 13.14.

At the moment, the HAL browser provides little benefit because the links in the entry point resource point to nonexistent resources. So this is your next task: to implement the Accounts API. As the entry point resource in Figure 13.14 shows, the Accounts resource needs to be accessible at http://localhost:4101/accountmanagement/accounts.

URI Templates

In building the Accounts API, you will see how to handle a common concern people have for hypermedia: inefficient navigation. Consider an API that exposes lots of data, such as thousands or millions of accounts. Clients may have to navigate hundreds of links to find the resource they want by successfully following links to the next page. Obviously, this can be massively inefficient for the client and the server—especially for public APIs with many concurrent clients. This problem is solved by using URI templates.

The following sample shows the Accounts resource, as HAL (JSON), that you are going to create an API for shortly. Look for the URI template; it’s the link whose templated attribute is set to true:

{
  "_links": {
    "self": {
      "href":"http://localhost:4101/accountmanagement/accounts"
    },
    "alternative": {
      "href":"http://localhost:4101/accountmanagement/accounts?page=1"
    },
    "account": [
      {
        "href":"http://localhost:4101/accountmanagement/accounts/{accountId}",
        "templated": true
      },
      {
        "href":"http://localhost:4101/accountmanagement/accounts/123"
      },
      ...
}

To represent URI templates, not only do you need to set the templated attribute to true, but you must also add placeholder sections in the URI. In the Accounts resource response just shown, you can see the placeholder is {accountId}. Clients of the API can then replace the placeholder with the ID of the account they are looking for. In doing so, you cut down hundreds of potential requests into just a single one. Creating URI templates with WebApi.Hal requires little effort, as you will now see while creating the Accounts API.

You can create the Accounts API by adding a new project called AccountManagement.Accounts.Api. You need to set this as a start-up project and ensure that it runs on port 4101. Once it’s created, you can then add a reference to WebApi.Hal by running the following command in the Nuget Package Manager console:

Install-Package WebApi.Hal -Project AccountManagement.Accounts.Api

The final configuration step is to set HAL as the default content type, as shown previously in Listing 13-9.

Two URIs will be exposed by the Accounts API. Initially, clients will click the Accounts resource at /accountmanagement/accounts, which represents the entire list of accounts. From there, clients will then navigate to individual accounts using the URI template contained within the Accounts resource—accountmanagement/accounts/{accountId}. To declare these routes in your project, the WebApiConfig in your AccountManagement.Accounts.Api project should resemble Listing 13-11.

As the route declarations in Listing 13-11 show, a class called AccountsController needs to be added to the Controllers folder (still inside AccountManagement.Accounts.Api). It needs two methods—Index() and Accounts()—as dictated by the route definitions. Starting with just Index(), the AccountsController should initially contain the code shown in Listing 13-12.

Most of the code in Listing 13-12 will be familiar from Listing 13-10, but it is worthwhile noting the additional links. The alternative link relation represents links that have a different URI but point to the same resource (self). One benefit of this is that clients can cache more efficiently by treating both URIs as the same resource. Below the alternative link is the templated account link, which WebApi.Hal automatically marks as templated because the href contains a placeholder.

Before you can test the new API in the HAL browser, you need to enable Cross-Origin Resource Sharing (CORS). This is because the Accounts resource is provided by a different vhost (port 4101 as opposed to 4100). The instructions for enabling CORS are detailed on the ASP.NET website (http://www.asp.net/web-api/overview/security/enabling-cross-origin-requests-in-web-api). Basically, you need to do the following:

1. Add the CORS package to the project by running the following command inside the Nuget Package Manager Console:

   
   Install-Package Microsoft.AspNet.WebApi.Cors -Project AccountManagement.Accounts.Api

2. Configure CORS in WebApiConfig, as per Listing 13-13.

If you run the HAL browser as before, starting at the entry point and following the link to the Accounts resource, you will see the URI template link, as per Figure 13.15.

URI templates are not all or nothing; you can combine them with normal links, even for the same resource. Figure 13.15 contains two nontemplated “account” links that illustrate this. They point directly to Account resources. For those links to work, though, you need to add an Account() method to the AccountsController. (This is determined by the route entry shown in Listing 13-11.)

An initial implementation of Account(), which returns just canned data, is shown in Listing 13-14. You can add this to your AccountsController below Index(). You also need to add the AccountRepresentation and Account classes from Listing 13-15. (You can put them all inside the AccountsController.cs file.)

A resource’s fields (as opposed to its links) are represented as standard JSON in an HTTP response. In Listing 13-15, you can see that an AccountRepresentation has the properties AcountId and Name. Therefore, if you navigate to an Account resource using the Hal browser, you will see these properties represented as plain JSON. Figure 13.16 also shows this.

Figure 13.16 also shows some noteworthy links. In particular, the three links that point to child resources of this account are followers, following, and blurbs. You’re going to build the followers endpoint in the next section, but the other two links are just to give you an idea of how a resource with many child resources could look. Building the followers endpoint is where you will start to build the event-driven parts of the system using the Event Store.

Persisting Events with the Event Store

Most of the infrastructure is in place for you to learn about building event-driven systems with REST. The first part of your learning involves storing events. There are many ways you can achieve this, such as writing events to a text file log or using a table in a SQL database. But in this example, you will see a purpose-built tool—the Event Store—that is the work of popular DDD practitioner Greg Young and his team (www.geteventstore.com).

To learn about storing events, you need to build a new endpoint in your Accounts API that returns the followers of an account. This endpoint supports the ability to add new followers to the collection by posting to it. This flow was previously illustrated in Figure 13.11. As usual, the first step to creating a new endpoint for exposing resources is to start with the route definition. Listing 13-16 shows how your WebApiConfig should be updated to add the route definition for the Followers endpoint.

Listing 13-16 shows that the Followers resource will be served up by a method called Index() on a controller called FollowersController. You can create that controller by adding a class called FollowersController, in your project’s Controllers folder, that resembles Listing 13-17.

The implementation of Index() in Listing 13-17 merely returns a canned response, parameterised with the passed-in Account ID. This is not the important part of this example—persisting an event in response to data being posted to the endpoint is the important and exciting part. You can see that process being triggered in Listing 13-18, which shows the code that needs to be added to your FollowersController directly below GetFollowers(). Also, you need to add the BeganFollowing class that is shown in Listing 13-19.

IndexPOST(), shown in Listing 13-18, responds to post requests for /accountmanagement/accounts/{accountId}/followers. You can see this because the method is attributed with the HttpPost attribute. Because of another method called Index () in the same file, the ActionName attribute indicates that it should still respond to requests for the Account Followers route even though this method is named IndexPOST().

The crucial event-persistence mechanics are not included in Listing 13-18. You can, though, see a call to EventPersister.PersistEvent(). This is the class that handles event persistence. You can see the contents of it in Listing 13-20, which shows the bare-minimum functionality for persisting events to the Event Store. You need to add this class to your project. For convenience, you can put it at the bottom of the AccountsController.cs file (but outside of the AccountsController class). Before adding the EventPersister, though, you need to install the Event Store C# client with the following command:

Install-Package EventStore.Client -Project AccountManagement.Accounts.Api

For the EventPersister to compile, you need to include the following using statements:

using EventStore.ClientAPI;
using Newtonsoft.Json;
using System.Net;
using System.Text;

Of the code shown in Listing 13-20, there are two key details to focus on: the event is converted to JSON (and then binary), and it is appended to a stream—the BeganFollowing stream in this case. You will get a better understanding of how all of this works once the Event Store is up and running.

Installing and Starting the Event Store

This example uses version 2.0.1 of the Event Store (http://download.geteventstore.com/binaries/EventStore-OSS-Win-v2.0.1.zip). Once you’ve downloaded it, you just need to extract the archive into a directory and then run the following PowerShell command from that directory (as Administrator):

./EventStore.SingleNode.exe --db .ESData

To confirm that the Event Store has started up successfully, you should be able to access the management application by going to http://localhost:2113. As confirmation of success, you are presented with the welcome page shown in Figure 13.17. If you don’t see the welcome screen, double-check that you ran PowerShell as Administrator. Also, look to see if there were any errors printed on the PowerShell console. If you do see the welcome page, that means the Event Store is running and is now patiently waiting to persist all your events.

Viewing Persisted Events with the Event Store Admin UI

You just saw a glimpse of the Event Store admin UI, and now you will explore some of its key features as you view events that are being created via the Accounts API. To get events into the system, you need to post details of new followers. For demonstration purposes, you can do all this through the HAL browser by going to the entry point (/accountmanagement in the Hal browser) after you have started the system. You then need to follow the link to the Accounts resource. From the Accounts resource, you need to follow the link to one of the dummy accounts, and from there follow the link to its followers resource.

If you want to post to the followers resource, you need to click the orange button in the NON-GET column for the row that represents the self link. This button is shown in Figure 13.18. Clicking this button opens a dialog enabling you to construct a JSON payload that will be posted to the endpoint. Figure 13.19 shows correctly formatted JSON being entered into this dialog containing the details of a new follower. Once you’ve entered some JSON, click the OK button, and your JSON is posted.

Providing you got a 200 response back from posting the JSON, you can now view the event using the Event Store’s admin UI. After navigating to http://localhost:2113/ and choosing the Streams menu item, you should see a stream called BeganFollowing that was created when you posted from the HAL browser. You can click on its name to view events in that stream. From there, you can inspect individual events, as shown in Figure 13.20.

Publishing Events to an Atom Feed

Atom is a discerning choice for exposing events in many RESTful systems because it is an extremely common format, as discussed earlier in the chapter. In this example, you will see how to use the tools baked into the .NET framework for creating and publishing an Atom feed.

Applications that publish events as an Atom feed are akin to message-publishing components in a messaging system. Accordingly, for an event-driven REST system, you can use a similar naming convention that communicates domain concepts, such as {BoundedContext}.{BusinessComponent}.{Component}.

To create the component that publishes the Began Following domain event, you can start by adding a new ASP.NET Web Application to the project called AccountManagement.RegularAccounts.BeganFollowing. You need to configure this application to run on port 4102 and make it a start-up project.

Creating a Basic Atom Feed in .NET

To create an Atom feed using official libraries that are part of the .NET work framework, you first need to add a reference to System.ServiceModel in the new AccountManagement.RegularAccounts.BeganFollowing project. After setting up a route definition, shown in Listing 13-21, you can then use classes from System.ServiceModel to create an Atom feed using events retrieved from the Event Store, as shown in Listing 13-22. The code in Listing 13-22 needs to be added as a new controller in the Controllers folder.

As you can see in Listing 13-22, an Atom feed is created using the SyndicationFeed class. The created feed is then set as the response of the HTTP request via an XmlWriter. On the response object, application/atom+xml is set as the content type. This will be passed directly as the value for the HTTP Content-Type response header. You can also see that individual events, retrieved from the Event Store (EventRetriever.RecentEvents()), are converted into FeedItems. But what you can’t see in Listing 13-22 is how to retrieve the events from the Event Store. That is shown next.

Retrieving Events from the Event Store

In Listing 13-22, individual feed items are generated by retrieving events from the Event Store using a custom utility class: EventRetriever. The contents of EventRetriever are shown in Listing 13-23 and need to be added to your project. To make life easy, you can pop it in the bottom of the file containing the BeganFollowingController if you don’t want to create another file.

EventRetriever is a utility class that wraps the Event Store C# client. It is hard-coded to retrieve the past 20 events, starting from the most recent. This is enabled by using ReadStreamEventsForward, which starts with the most recent events and works backward. There’s a lot of functionality provided by the Event Store C# client that isn’t covered in this book, so if you’re thinking about using the Event Store and the C# client, the Event Store website contains lots of useful information.

For the EventRetriever to compile, you need to add a reference to the Event Store C# client in this project as well. The following command takes care of installing it for you:

Install-Package EventStore.Client -Project AccountManagement.RegularAccounts.BeganFollowing

To test that your Atom feed is working as expected, you first need to update the entry point resource (in the AccountManagement.EntryPoint.Api project) to provide a link to the Atom feed (remember, clients should not be coupled to resources, only the entry point). Listing 13-24 shows the updated entry point resource containing the required link. Once the resource is added to your project, you can test the feed by viewing it directly in a browser (accessing a resource directly is okay if you’re just testing it): http://localhost:4102/accountmanagement/beganfollowing.

Archiving Feeds

In a highly scalable system with potentially millions of users, there may be hundreds or thousands of events every second. Having a single Atom feed for all these events would quickly become unusable. This could result in a massive waste of network bandwidth, as well as other inefficiency-related issues. A common solution is to display a fixed number of events per-feed, and once a capacity is reached to then archive the feed. Importantly, each feed contains hypermedia links to the previous and next archives (if they exist). For more information, the Internet Engineering Task Force (IETF) has a request for comments (RFC) titled “Feed Paging and Archiving” (https://tools.ietf.org/html/rfc5005).

Creating an Event Subscriber/Atom Feed Consumer

Consuming an Atom feed that exposes domain events is akin to subscribing to messages in a messaging system. However, consuming an Atom feed inverts the process of receiving pushed messages by polling and pulling them instead. It’s a little more work up-front for developers, but it definitely has compelling advantages.

When creating a consumer of an Atom feed, you can again take advantage of Atom’s popularity by using official libraries in the .NET framework. You’ll see this shortly as you build the first part of the Discovery bounded context that polls the Began Following Atom feed. The project you create for this does not need to be a web project. Instead, you can create a new C# Class Library called Discovery.Recommendations.Followers (as per the containers diagram in Figure 13.10). As before, to take advantage of .NET’s really simple syndication (RSS) libraries, you need to add a reference to System.ServiceModel. You also need to configure this project as a start-up project.

Subscribing to Events by Polling

Inside the new polling component, the logic you are about to add consists of a few generic steps. These steps are likely to be similar in any Atom-feed polling application you build.

1. Fetch a batch of events starting from the last event ID that was processed (or the first item if no event has been processed yet).
2. Process each item in the batch according to domain policies.
3. Store the ID of the last event processed.

The first part of implementing the polling consumer for the Discovery bounded context is shown in Listing 13-25. This contains only the high-level logic. You can add all this code to your project inside a single class called BeganFollowingPollingFeedConsumer in the root of the project.

Listing 13-25 shows the first part of the feed consumer. It illustrates how a batch of events will be retrieved from the feed and processed. You can see polling is set to a maximum of once per second with the call to Thread.Sleep().

Focus now shifts to the lower-level details of actually fetching the feed. This is shown in Listing 13-26; it’s an example of a REST API client following links in hypermedia from an entry point to a target resource. You need to add this code directly below the code you added from Listing 13-25. You also need to add ServiceStack.Text to the project by running the following command:

Install-Package ServiceStack.Text -Project Discovery.Reccommendations.Followers

The code in Listing 13-26 also depends on the classes in Listing 13-27 and the following using statements, which need to be added in the same file:

using ServiceStack.Text;
using System.Xml.Linq;

After fetching the feed, individual events can then be processed. A demonstrative implementation of this for the BeganFollowingPollingFeedConsumer is shown in Listing 13-28.

Listing 13-28 demonstrates the generic high-level logic you would likely see in a feed consumer. First you fetch a batch of events from the feed, then you select the ones that have not yet been processed. In some cases where feeds are paged or archived, you may need to make additional requests, again using hypermedia, to locate the last event processed. After locating the events that are unprocessed, you then process each one according to your domain rules and update the ID of the last processed event.

You may be wondering how errors are handled during the processing of events. With REST-based integration, there is no out-of-the-box support for poison messages or transitive messages. This is covered in a touch more detail toward the end of the chapter.

To complete the example, you need to implement the remaining piece of lower-level logic, which parses events from the feed. This is shown in Listings 13-29 and 13-30. You also require a final pair of using statements:

using System.IO;
using System.Xml;

That wraps up the example for this chapter. Hopefully you’ve understood enough theory and seen enough examples to feel confident about considering REST as an option for bounded context integration on your projects.

All that remains for this example is to test that everything works. You can do that by POSTing new followers, as shown previously. Keep an eye on the console window that automatically pops up. You should see output similar to Figure 13.21. You can also access the Atom feed directly in the browser again to check the new events that appear on it.