Introduction
In this multipart tutorial, you’ll build a simple web API for managing a list of project items. You’ll build a pure backend API without creating any UI in this tutorial.
Through this example project, I’m going to summarize the principles, design patterns, and tools used when you are creating a RESTful Web API, so this tutorial would have multiple chapters. We would start with a very simple Web API, but as the tutorial progresses, the project gets more and more complex.
I would like to demonstrate modern REST API design principles, like OData and API Endpoints (instead of MVC controllers); integration test tools, such as SpecFlow; common design patterns useful when writing Web APIs (e.g. Dependency Injection, Repository Pattern, CQRS Pattern), and other useful packages (like Swagger, AutoMapper, FluentValidation, etc.) You could find a detailed list of my plans below (see: Wannabe Sections)
Prerequisites
I expect you to have knowledge of object-oriented programming concepts.
Even though I’m going to cover many details of the C# programming language, it doesn’t hurt if you have basic knowledge of this subject.
I also assume you know what REST is, how the HTTP protocol works, what are API endpoints, and what is JSON. Here is a great introductory tutorial on this subject.
The final requirement is that you understand how relational databases work.
To code along with me, you will need the .Net 6.0 Software Development Kit and a developer tool. I personally recommend Visual Studio 2022 Community Edition, which includes the .Net 6 SDK, as well.
You can also choose another code editor to develop the API, such as Visual Studio Code. In this case, you need to manually download the .Net 6.0 SDK. I also recommend installing the C# extension for Visual Studio Code to have better code highlighting. Choose the code editor you prefer.
I confess, Visual Studio Community Edition and Visual Studio Code exist side by side on my machine — simply because VSCode can solve certain tasks simply more conveniently.
You also might install Postman, the tool I’m going to use to test the API.
About the example project
The “guinea pig” of the following posts will be the backend of an infinitely simple project management system, the sonically named “Advanced Project Manager API“, or APM.API for short.
Endpoints implement operations related to Project and User entities (create, read, modify and delete – CRUD). There is an n:m relationship between Projects and Users: each User can participate in 0 or more Projects, and each Project can have 0 or more participants. The connection is realized through License entities: a User is connected to a specific Project with some kind of Permission (Read, Write, Admin) ensured by a License. The same User can have several Licenses for the same Project, each of them ensuring different Permission for him.
The status of Projects is reflected by Milestone entities: each Project has a Milestone, which expresses the current status of the Project (e.g. Not-Started, Blocked, In-Progress, Finishing, Compete, etc.). The Milestones are not wired in into the system, you can add any Milestones you like via the API.
The Entity Diagram below illustrates what has been said:
In the sequel,
… we will build the first version of the Web API
Wannabe Sections
If you want to make God laugh, tell him about your plans.
Woody Allen
- Building Your First Web API
- Adding CRUD endpoints and testing them with Postman
- Data Services and logging – Dependency Injection, Serilog
- Persisting data in a real database – Entity Framework
- Unit Tests with Mocks and Coverage Reports. An introduction to TDD
- Dealing with User entities – the Repository Pattern
- Mapping between DTOs and Models using AutoMapper
- Validating input data using FluentValidation
- Configurable services – the Options pattern and its implementations
- Expelling Exceptions – the Operation Result pattern and a little taste of Benchmarks
- Farewell from the Controllers: introducing API Endpoints. The CQRS Pattern
- Data Relations and the Unit of Work Pattern
- Integration Tests using an in-memory database. Introducing SpecFlow
- Turning to a MySQL database using Docker
- Sending source code to Azure DevOps using automated build pipelines
- Deploying the API into the Azure Cloud
- Creating NuGet packages by Azure DevOps pipelines
- How to deal with package version numbers. Introducing GitVersion
- User Authorization by JWT tokens
- Data filtering and paging. Introducing OData.
- HATEOAS – Self-descriptive API endpoints
- API lifecycle – Versioning and Deprecation
- …
Useful links
- FreeCodeCamp.org: RESTful Services Part I: HTTP in a Nutshell
- Json.org: An Introduction to JSON
- MDN Web Docs: An overview of HTTP
- Microsoft Docs: C# Documentation