Bevezetés
Ma egy sokrészes segédletet indítok, amiben egy egyszerű web API-t fogunk összerakni. A segédletben kifejezetten a backend API-ra koncentrálunk, nem építünk UI-t hozzá.
A példa projektben segítségével megpróbálom összefoglalni azokat a tervezési mintákat, fejlesztési elveket és eszközöket, amelyeket egy REST Web API létrehozásakor használunk. Egy nagyon egyszerű Web API alkalmazással fogunk kezdeni, ami úgy válik egyre összetettebbé, ahogy a segédletben haladunk.
Olyan modern REST API tervezési elveket akarok bemutatni, mint az OData és az API Endpoint-ok (MVC Controllerek helyett); integrációs tesztelésre szolgáló eszközöket, mint a SpecFlow; a Web API-k kódolásakor használható elterjedt tervezési mintákat (pl. Dependency Injection, Repository Pattern; CQRS Pattern); valamint egyéb hasznos csomagokat (mint a Swagger, AutoMapper, FluentValidation, stb.) Később részletesen is kifejtem a témákat (lásd: Szekciók)
Előfeltételek
Számítok rá, hogy tisztában vagy az Objektum Orientált Programozás koncepciójával.
A példák során ugyan el fogom magyarázni, ha valami különleges eszközt használunk a C# programozási nyelvből, de nem árt, ha legalább a nyelv alapfogalmait ismered.
Arra is számítok, hogy tudod, mi az a REST, hogyan működik a HTTP protokoll, mik azok az API Végpontok (endpoints), és mi az a JSON. Ezekről a témákról itt találsz egy kitűnő bevezető segédletet angol nyelven.
Hogy velem együtt kódolj, szükséged lesz a .Net 6.0 Szoftver Fejlesztési Csomagra (SDK) és egy fejlesztő eszközre. Személy szerint a Visual Studio 2002 Community Edition változatát ajánlom, ami tartalmazza a .Net 6.0 SDK-t is.
Az API fejlesztéséhez választhatsz más szerkesztő programot is, pl. a Visual Studio Code is remek választás. Ez esetben viszont kézzel kell letöltened a .Net 6.0 SDK-t. Célszerű feltenni hozzá a C# extension for Visual Studio Code bővítményt, amivel jobb kódkiemelést és intellicensz szolgáltatásokat fogsz kapni.
Bevallom, a gépemen egymás mellett létezik a Visual Studio Community Edition és a Visual Studio Code — egyszerűen azért, mert bizonyos feladatokat a VSCode egyszerűen kényelmesebben meg tud oldani.
Az API kézi teszteléséhez a Postman az egyik legjobb eszköz, érdemes azt is telepíteni.
A példa projektről
A további bejegyzések “állatorvosi lova” egy végtelenül egyszerű projekt menedzsment rendszer backendje lesz, a hangzatos nevű “Advanced Project Manager API“, vagy röviden APM.API.
A végpontok projektekkel (Project) és felhasználókkal (User) kapcsolatos műveleteket valósítanak meg (létrehozás, olvasás, módosítás és törlés – CRUD). A projektek és a felhasználók között n:m kapcsolat létezik: minden felhasználó 0 vagy több projektben vehet részt, és minden projektnek 0 vagy több résztvevője lehet. A kapcsolat licensz (License) entitásokon keresztül valósul meg: egy Felhasználó valamilyen konkrét Engedéllyel kapcsolódik egy adott Projekthez (Read, Write, Admin), amelyet egy Licensz biztosít számára. Ugyanannak a Felhasználónak lehet több Licensze is ugyanahhoz a Projekthez, de valamennyi Licensze különböző Engedéllyel ruházza fel.
A Projektek állapotát Mérföldkő (Milestone) entitások tükrözik: minden Projekthez egy Mérföldkő tartozik, ami a Projekt aktuális állapotát fejezi ki (Not-Started, Blocked, In-Progress, Finishing, Compete, stb.). A Mérföldkövek nincsenek előre beégetve a rendszerbe, az API-n keresztül tetszőleges Mérföldköveket vehetünk fel.
Az elmondottakat az alábbi Entitás Diagram teszi szemléletessé:
A folytatásban…
…megépítjük a Web API legelső változatát.
A leendő fejezetek
Ha meg akarod nevettetni Istent, mesélj neki a terveidről.
Woody Allen
- Építsünk Web API-t
- Készítsünk CRUD végpontokat, és teszteljük őket Postman-nel
- Adat szervízek és naplózás – Dependency Injection, Serilog
- Az adatok mentése valódi adatbázisba – Entity Framework
- Unit-tesztelés Mock objektumokkal és Coverage Riportok. Bevezetés a TDD-be
- User entitások kezelése – a Repository Pattern
- DTO és Model objektumok meppelése AutoMapper segítségével
- Az input adatok érvényességének ellenőrzése FluentValidation segítségével
- Konfigurálható szervízek – az Options minta és implementálása
- Felhagyunk a kivételekkel – az Operation Result minta és egy kis ízelítő a Benchmarkokból
- Búcsú a Controllerektől, bemutatjuk az API Végpontokat. A CQRS minta.
- Adat-kapcsolatok és a Unit of Work minta
- Integrációs Tesztek in-memory adatbázison. A SpecFlow bemutatkozik.
- Váltás MySQL adatbázisra Docker segítségével.
- A forráskód felküldése Azure DevOps-ba automatizált build pipeline segítségével
- Az API telepítése az Azure Felhőbe
- NuGet csomagok létrehozása Azure DevOps pipeline-ok segítségével
- Megbirkózunk a csomagok verzió számaival is. A GitVersion bemutatkozik.
- Felhasználók azonosítása JWT tokenekkel
- Adatok szűrése és lapozás. Bemutatjuk az OData szabványt.
- HATEOAS – Ön-dokumentáló API végpontok
- API életciklus – API-Verziók és “Értékcsökkenés”
- …
Hasznos linkek
- 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