Evolution is the key

Designing Evolvable Web APIs with ASP.NET by Glenn Block, Pablo Cibraro, Pedro Felix, Howard Dierking, Darrel Miller

I think that Web API was an interesting addition to the Microsoft Web stack. We started with Web forms as a way of allowing people to (try to) write their web applications in the style of a desktop windows form application. Some of the weaknesses of this were patched when ASP.NET MVC came along, but over time the focus moved to writing the client side of web applications entirely in JavaScript and there was a need for a better framework for writing non-GUI server code that was there simply to serve data for the clients to consume. The book demonstrates the use of Web API in this wider setting, but also covers a lot more, pushing the reader to implement HTTP as it was originally conceived, with its notions of discoverability (via links), content negotiation (using accept to get different renderings of the same data depending on the clients needs), cache friendliness (by making sure that GET really is idempotent, and by using Etags to make it possible to verify if data has changed) and using the proper HTTP verbs for updating data.

You can tell the book was written by a group of authors, as the flow isn’t the same as a single author book, but given the range of diverse topics that are covered, the need for multiple authors isn’t at all surprising.

The first two chapters give a very good overview of HTTP, covering topics ranging from the HTTP methods (verbs) to a great summary of all the various headers, status codes, caching and authentication. The book then covers the difference between using HTTP as a means for REST (representational state transfer) compared with using it for RPC style SOAP messages. The authors give a great case for supporting the former style.

The book then covers ASP.NET Web API, covering the hosting layer, the message handler pipeline and controller handling.

We then go into chapters that discuss things at a higher level – choices for mapping URLs to resources, what it means for an API to be evolvable and the design of media types. These ideas are then used to implement an API for an issue tracking system. We get a whole chapter on improving the API and a chapter on designing the client. The whole time the authors focus on testability, emphasising how the Web API implementation allows us to unit test the implementation by offering simple instantiable implementations that can be used from tests, with loads of C# to demonstrate the implementation.

Later chapters get low level again, covering the hosting model, controllers and routing in detail, formatter and model binding which allow your code to work at the domain level instead of the byte level, and HttpClient, the new way of accessing resources via the web. Chapters on security, OAUTH and testability finish the book.

This book is a great way to learn about modern HTTP APIs such as those being developed by GitHub. The coverage of Web API is really good, describing in some detail the design ideas behind the implementation. I zoned out a little while reading the chapters on media types, but now realise how important they are and so will definitely go back and read them. Well worth a read, as Web API is definitely the future  given its support for SPAs.

This entry was posted in Books. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s