Designing Evolvable Web APIs with ASP.NET

Chapter 7. Building the API

The proof of the pudding is in the eating, so let’s eat.

In the previous two chapters, you learned about the design of the issue tracker system, and the media types that it will support for its interactions. Throughout this chapter, you’ll see how to build the basic implementation of the Web API that supports that design. The goal for this exercise is not that the API should be fully functional or implement the entire design. It is to get the essential pieces in place that will enable us to address other concerns and to evolve the system.

This chapter is also not going to delve into too much detail on any of the individual parts, as the focus here is to put the pieces together. Later chapters will cover each of the different aspects of ASP.NET Web API in more detail.

The Design

At a high level, the design of the system is the following:

1. There is a backend system (such as GitHub) that manages issues.
2. The Issue collection resource retrieves items from the backend. It returns a response in either the Issue+Json or Collection+Json formats. This resource can also be used for creating new issues via an HTTP POST.
3. The Issue item resources contain representations of a single issue from the backend system. Issues can be updated via PATCH or deleted via a DELETE request.

4. Each issue contains links with the following rel values:

   self

   Contains the URI for the issue itself

   open

   Requests that the issue status be changed to Closed

   close

   Requests that the issue status ...