Welcome!
Approach
Hello and welcome to the API Book .NET!
Here you will (eventually) find a complete step by step build guide to creating a fully-fledged .NET 8 REST1 API that has the features and functionality of a production ready solution.
Why eventually?
I intend to write this book as and when I have the time, and I’ll release sections when they are ready. So depending on where you are in the writing process, this book is either very early in its development, or close to completion (I don’t think it will ever be complete, more continually evolving…)
Structure
If you’re anything like me, when following step by step tutorial type books, I lke to GET ON WITH IT! I prefer to dive into the practical as that’s where I learn best, and refer to deeper theory later (and sometimes not at all 😏). With this in mind the book is comprised to 2 big sections:
1. The Build Guide
The build guide is basically a step by step narrative on how to build the API, and the approach I’ve taken to structuring it is to segment it by build iterations. So the first build iteration will produce something quite basic, the next slightly more advanced, and so on…
Each iteration will deliver something of value, that works - you can read more about this in the Iterate section.
What about theory?
While I may mention, or elaborate on some theory in the Build Guide, I will keep it brief. Deeper discussion on theory will referenced in the 2nd section which is…
2. Theory
Pretty straightforward really, this section will contain elaborated theory that readers should find useful - it’s designed to supplement the Build Guide.
Links to Theory will be identified with the 📖 emoji.
Build comes first
As already mentioned, sections of the book will be released as and when they are ready, with a focus on the Build Guide. It is conceivable therefore, that I may reference empty theory sections.
I create and reference empty theory sections deliberately so I know what sections I still need to write! Don’t worry though, I’ll get to them all… eventually.
What are we learning?
While the title of the book is somewhat generic (apibook) the domain suffix (.net) is not, and is indeed a reference to the .NET framework, (and not because apibook.com was already taken - honest).
So yes, in short we’re learning about building APIs using .NET, specifically:
- .NET 8
- C# language
- REST APIs (to begin with at least)
.NET 8
As I write this sentence (Saturday 7th of September 2024) the latest version of .NET is at version 8, so I think it makes sense for me to write a book with this version in mind.
Moreover, .NET 8 is a Long Term Support version (LTS) of .NET, which means that it is supported for 3 years, as opposed to Standard Term Support (STS) versions that are only supported for 1.5 years.
Microsoft alternates .NET versions between LTS and STS, meaning that when .NET 9 is released (currently November 2024), it will be out of support before .NET 8 as it is an STS version. This is another reason why I’m targeting .NET 8.
LTS forever
I’ve made the decision to only create content on LTS versions of .NET, not just because they are supported longer, but because the cognitive load on attempting to keep up with the .NET release cycle is too much for my almost half-century old brain now… 🤯
If there are some totally amazing features in an STS versions, I may break this rule.
C#
As we are using .NET 8 to build our API, we theoretically have a choice of languages:
- C#
- Visual Basic .NET
- F#
For me though, this is a no-brainer, and the choice is obvious - we’ll be using C#. End of conversation.
REST
When we talk about “web APIs”, by far the most popular design pattern is REST (REpresentational State Transfer). So to start with, we’ll be building an API using the REST pattern, not just because it’s widely adopted, but because it’s good pattern, and easy to pick up.
However this book is called: the API Book .NET, so aren’t we going to cover things like: GraphQL, gRPC etc? The answer to that is hopefully, but again, as this is an evolving work my primary focus will be REST.
Iterate
Don’t run away, I’m not going to get on my soap box and talk at length about agile software development. I am however going to rely heavily upon an iterative approach to building out the API project. We’ll start off with Iteration 0 which is a discovery / design iteration intended to get us aligned on what we’re building, and how we’re going to build it, before we actually start building.
We’ll then progress through successive build iterations, the first of which will provide us with a fully working API, all be it one that you probably wouldn’t use in production. From there, each of the following iterations will introduce new functionality, and or build concepts - such a version control with Git and GitHub.
The goal of each iteration is to “move the needle” and deliver something of value, or deliver value in a more effective way.
Scrum?
For those of you versed in agile software development, an iteration may sound strikingly similar to the concept of a sprint that you would find in Scrum.
Indeed you would right - they are similar. The reason I chose to use iteration over sprint is that I didn’t want to get bogged down (yes this is an oxymoron), in the nomenclature of scrum.
The iteration plan I have for the book is outlined below - I’ll revisit this from time to time as the book evolves, so don’t be too alarmed if it looks quite sparse:
| Iteration | Goal(s) |
|---|---|
| Iteration 0 | Algin on the tools we’ll use, setting those tools up into a working development environment, and understand the design of the overall API solution. |
| Iteration 1 | Build out a REST API with 5 endpoints |
| Iteration 2 | Adopt Continuous Integration / Continuous Deployment (CI/CD) using GitHub, GitHub Actions and Azure This iteration can be skipped if you don’t want to use this tech - however deploying to production early is key concept in building valuable software that works in the real world. Recommended even if you only read the chapter. |
| Iteration 3 | 🤔 Ummm - not sure yet. |
Code
The code for the book can be found on GitHub with each iteration represented as a separate folder in the repository.
Clone, copy or type?
Because I have provided the code, you can choose to “follow along” using one of the methods below:
- Clone the repo and just run the code. This is fine, but in my view the least rewarding, and if you’re a new developer, least likely to help you embed the concepts.
- Copy sections of code from the repo. This is kind of a hybrid between the first and the last option. Here you may perform some aspects of the build yourself, (e.g. scaffold the app), but copy small (or large) sections of code from the GitHub repo. I have used this approach, but you need to be careful that you take time to actually read the code and understand what it’s doing. There is a temptation just to copy / paste and learn nothing.
- Type the code in. This of course takes the longest time, but I feel if you’re a newer developer that this is the best way to actually learn2, most usually because you’ll make a ton of mistakes - and that’s the best way to learn!
Print Version
🌳🌳 All the trees out there will be happy to know there is no print version. 🌳🌳
Supporting the Book
There are a number of ways you can support me writing this book:
- Just read the book! Reading the book is the best way to reward me, and I take great pleasure from the fact I may have helped someone learn something new
- Submit a PR. This option isn’t actually available yet as the GitHub repository for this book is currently private while I get a few sections done. Eventually though I’d welcome other contributors to help build out the book, identify and submit corrections etc…
- While I don’t do this for the money (if that was my driving force I’d be very disappointed!), if you’re feeling that way inclined then I’m always open to being bought a coffee to help me through the long nights writing!
Errata
As mentioned above, PR’s will eventually be welcome, in the meantime if you spot any errors email me at: les.jackson@apibook.net