Contents
Chapter 1: API Design Demystified ..................................................................................... 1
The Importance of APIs ............................................................................................................... 1
REST: The Good, Bad, and Ugly ................................................................................................... 3
Principles of REST ....................................................................................................................... 5
Wrapping Up .............................................................................................................................. 7
Chapter 2: Introduction to ASP.NET Core ........................................................................... 9
What Is ASP.NET Core? ............................................................................................................. 10
NET Core vs .NET Framework .................................................................................................... 11
Why Use ASP.NET Core? ............................................................................................................ 11
The .NET Ecosystem .................................................................................................................. 12
ASP.NET Core Features .............................................................................................................. 13
Tooling Available for ASP.NET Core ............................................................................................. 13
Setting Up the Development Environment .................................................................................... 16
A Lap Around the .NET Core CLI ................................................................................................. 19
Wrapping Up ............................................................................................................................. 22
Chapter 3: Your First API Application ................................................................................ 23
Getting Started .......................................................................................................................... 23
Dependency Injection ................................................................................................................ 29
Application Startup .................................................................................................................... 30
Creating an Endpoint ................................................................................................................. 33
Wrapping Up ............................................................................................................................. 36
Chapter 4: Extensibility Architecture ................................................................................. 37
Hosts and Servers ...................................................................................................................... 37
Creating a Custom Server ........................................................................................................... 41
Middleware ................................................................................................................................ 49
Routing ..................................................................................................................................... 54
Hosted Services ......................................................................................................................... 57
Wrapping up .............................................................................................................................. 59
Chapter 5: MVC .................................................................................................................. 61
The MVC Pattern ........................................................................................................................ 61
MVC in ASP.NET Core ................................................................................................................. 62
Controllers and Actions ............................................................................................................... 64
Model Binding and Validation ...................................................................................................... 75
Filters ........................................................................................................................................ 86
Formatting Responses ................................................................................................................ 89
Application Parts ........................................................................................................................ 93
Wrapping Up ............................................................................................................................. 94
Chapter 6: The Configuration Model ................................................................................. 95
Basic Configuration .................................................................................................................... 96
Configuration Providers .............................................................................................................. 99
Strongly Typed Configuration .................................................................................................... 106
Working with Changes .............................................................................................................. 110
Wrapping Up ............................................................................................................................ 111
Chapter 7: Logging and Error Handling ........................................................................... 113
Adding Logging ........................................................................................................................ 114
Log Anatomy ........................................................................................................................... 116
Grouping and Filtering .............................................................................................................. 121
Different Logging Providers ...................................................................................................... 125
Dealing with Exceptions ........................................................................................................... 127
Wrapping Up ........................................................................................................................... 130
Chapter 8: Securing APIs ................................................................................................ 131
Authentication & Authorization ................................................................................................. 132
Protecting Sensitive Data ......................................................................................................... 140
Enforcing SSL ......................................................................................................................... 145
Cross-origin Requests ............................................................................................................. 146
Request Rate Limiting ............................................................................................................. 149
Wrapping Up .......................................................................................................................... 153
Chapter 9: Bells & Whistles ........................................................................................... 155
HATEOAS .............................................................................................................................. 155
Versioning ............................................................................................................................. 165
Swagger ............................................................................................................................... 173
GraphQL ............................................................................................................................... 177
Wrapping Up ......................................................................................................................... 184
Chapter 10: Testing & Debugging ................................................................................. 185
Why Is Testing Important? ..................................................................................................... 185
Unit Testing ........................................................................................................................... 186
Dealing with Dependencies ..................................................................................................... 192
Integration Testing ................................................................................................................ 194
Debugging .NET Core and ASP.NET Core Sources .................................................................... 199
Wrapping Up ......................................................................................................................... 201
Chapter 11: Hosting & Deployment ............................................................................... 203
Hosting on Windows .............................................................................................................. 203
Hosting on Linux ................................................................................................................... 209
Hosting on Docker ................................................................................................................. 212
Publishing to Azure ................................................................................................................ 217
Continuous Integration & Deployment ..................................................................................... 221
Wrapping Up ......................................................................................................................... 227
Index .................................................................................................................................... 229
Foreword
The .NET community has been re-energized by the enthusiasm building behind open source .NET Core. Engineers who have invested years in .NET and ASP.NET are now able to run their code cross-platform on Windows, Linux, Mac, and more. They can make micro-services and run them in containers as well as within container orchestrators like Kubernetes.
There’s a ton of new standards and new architectures to learn and explore. There’s new open source libraries and new best practices. REST has cemented itself as a must-know architectural style. We need to learn the principles of REST and how those principles map to features in ASP.NET Core 2.0. We also need to expand our web APIs with the power of GraphQL, which will allow us to query our APIs with this exciting emerging standard. And we need to document our APIs with the Open API specification (Swagger).
The book you’re holding now is a fantastic entry point for developers both new and old. You’ll learn all about .NET Core from the CLI (command-line interface) on up, then build ASP.NET RESTful web services to power any system’s back-end. You’ll explore best practices for unit and integration testing your services, then for lock-down services with authentication and authorization using open standards. This book is full of practical examples of how to design modern APIs to power websites and mobile apps.
Finally, you’ll examine not only how to deploy your code to on-premises servers or the cloud, but also how to do it with continuous integration and continuous deployment. Check in your services and see them tested and deployed automatically! Your .NET web services are now cross-platform, fast, and modular!
I’m thrilled to have played a small part in the open sourcing of .NET and ASP.NET. I’m looking forward to seeing what you build with the ASP.NET Core 2 open source web framework!
Introduction
Do you have interest in designing elegant enterprise-grade APIs that can scale and run on any platform? Are you always looking for the next big thing by staying on the forefront of the latest technologies? Do you want to expand your knowledge by learning ASP.NET Core?
Modern API Design with ASP.NET Core 2 is formulated to help the all-around developer gain useful skills for developing APIs in ASP.NET Core 2 and is based on proven industry patterns and practices, like REST. The book covers a wide range of topics with regards to building as well as deploying scalable and cross-platform API solutions. In chapter 1, I will introduce you to APIs and the vital role they play in our world today. I will also demystify what REST is and what it means for an application to be RESTful by covering the six principles of REST that were introduced by Roy Fielding.
The chapter 2 is all about getting familiar with ASP.NET Core by learning what it is and how its features align with REST. You also will look at the different tooling that is available for building an API.
In Chapter 3, you will start to create your first API with ASP.NET Core and learn about the essential aspects of its components, like dependency injection and the application startup bootstrapper.
In Chapter 4, you will delve into the extensibility architecture of ASP.NET Core and learn how to create a custom HTTP server by using the file system to process incoming requests. You will discover the concepts of middleware and routing to process and route requests to the particular receiving logic of your application, as well as how hosted services can help run background tasks.
After a quick introduction of MVC in Chapter 5, you will explore what ASP.NET Core MVC is and how it compares to its predecessor in the previous versions of ASP.NET, and you will learn about implementing an API using ASP.NET Core MVC. I will also cover essential features of the framework, like model binding and model validation, filters, formatters, and application parts.
Chapter 6 is all about configuration as you learn about the new configuration model of ASP.NET Core and the different ways of managing configuration data, which originates from multiple sources, within your application.
I will briefly cover application logging and exception handling in Chapter 7, and you’ll learn the different techniques that we can apply to gain useful insights from the application at any given moment in time.
As I move onto the topic of security, you’ll learn about the differences between authentication and authorization as well as the different authentication schemes that are available when working with server applications. In Chapter 8, I’ve also implemented JWT authentication, and you’ll learn about protecting sensitive data using the ASP.NET Core data-protection stack, enforcing SSL, and implementing rate-limiting to prevent DoS and DDoS attacks.
Chapter 9 is all about adding extra value to our APIs, as you discover how to implement HATEOAS in an ASP.NET Core application, before moving onto the topic of versioning. Furthermore, you will learn technologies like Swagger and GraphQL to make APIs stand out from the rest.
You’ll learn about the importance of testing in Chapter 10, and you’ll witness some examples of unit and integration tests before learning how to debug the compiled source code of ASP.NET Core using Source Link.
Marking the end of the book, Chapter 11 is all about hosting and deploying ASP. NET Core applications to different hosts, like IIS, Linux, Docker, and Azure, as well as implementing continuous integration and continuous deployment using VSTS and Azure. As a final thought, I hope that you enjoy reading this book as much as I enjoyed writing it, and I am very grateful for having such an opportunity to publish my work and experiences.
Using This Book
This book is broken down into different chapters, each covering a range of sections relating to that topic of the chapter. When a code is discussed, the irrelevant parts of the code might be omitted inside the code block with an ellipse (…), for simplicity and to keep the focus on the right place. Because the technology mentioned in this book is cross-platform, when shell commands are executed, each line will be prefixed with a dollar sign ($) to indicate a new command line and is not indented to be part of the command.
API Design Demystified
The times have changed—we commute with Uber, overnight with Airbnb, pay with cryptocurrencies, and have breaking news at our fingertips via social media. We snap, chat, and share our lives in real-time and these kinds of apps make it happen.
What drives most of these apps, however, are Application Programming Interfaces (APIs), which are the glue of the connected world we live in. APIs are everywhere, from the doorbell in our smart homes to the traffic updates in our connected cars. In web development, an API is a set of rules or contracts that dictate how consumers should interact with services by explicitly defining expected inputs and outputs. This is an architectural approach to abstract away the definition from the implementation.
In this chapter, we will address the importance of APIs by understanding what they are as well as by getting introduced to the different architectural styles of web API design. We will then zoom into the REST architectural style and, by applying the six principles of REST, learn what it means to have a RESTful service.
The Importance of APIs
In today’s modern, connected world, the API is one of the most critical elements of cloud-based services. Having billions of services out there for consumption requires good abstraction to promote compatibility, usability, and maintainability.
The API plays a crucial part in the integration of two systems, as it enforces a standardized communication link between them. For example, an electrical drill needs power from an electricity source for it to work. To be able to connect electrical equipment to power sources, we need a wall socket and a plug.
In this analogy, the wall socket is the API for providing electricity, and the drill is the consumer, as it uses a specific plug to be able to connect to power. One could, of course, connect the drilling machine directly to the wiring circuit, but it would require more manual work and be very unsafe. Imagine having to hardwire everything in your home; the result would be a mess. The point here is that having a plug and wall-socket mechanism drastically improves interoperability, allowing devices to be pluggable given a standard interface.
Web APIs are no different, as they ensure that systems can communicate seamlessly without the complexity of hardwiring. In fact, an API promotes accessibility by allowing multiple systems to use one implementation of business logic, regardless of their technology stack.
Imagine if the National Weather Service had to explicitly implement a system-integration point for each of its consumer systems. Updates and maintenance would be a nightmare, and that apparently wouldn’t scale very well. Instead, implement an API to facilitate the flow of data in one standard way. Doing this also opens up the door to other possibilities, like integration with third-party systems, which can lead to opportunities to monetize on some of the internal components.
Other benefits of providing an API are control and analytics. It is vital that you secure sensitive endpoints, and having a mechanism to control access is paramount. There is a Dutch saying, “meten is weten,” which means measuring is knowing. Understanding how services are used provides useful insights on feasibility and potential optimizations. APIs can be implemented in many different architectural styles. The most common styles that are used in the industry are RPC, WSDL, SOAP, and REST. When designing an API, it is important to use the right style for the problem at hand, as each of the styles has its advantages and disadvantages.
