REST API w ASP .NET Core

Usługa REST API w ASP .NET Core to dużo mniej kodu w porównaniu do ASP.NET a więc stworzysz ją szybciej, łatwiej oraz lepiej.

W tym artykule pokażę Ci jak od podstaw stworzyć REST API przy użyciu ASP .NET Core, dotnet CLI oraz Visual Studio Code. Aby odczarować powszechne przekonanie, że .NET jest jest tylko na Windowsa aplikacja powstał na macOSie.

Wymagania biznesowe

Aplikacja, która za chwilę powstanie – Warsaw Stops API, będzie dość prosta. Ma bazę danych wszystkich przystanków tramwajowych i autobusowych w Warszawie. Każdy przystanek ma kilka informacji np. kierunek odjazdu, nazwę przystanku, numer przystanku i najważniejsze -koordynaty GPS. Warsaw Stops API jest backendem do aplikacji mobilnej/webowej, której zadaniem jest wyszukać na podstawie fragmentu nazwy przystanek, pokazać go na mapie na następnie nawigować do niego.

Założenia techniczne

Do projektu na samym początku dodam Swaggera. Jest to narzędzie, które automatycznie wygeneruje dokumentację do API oraz UI, które pozwoli na wygodne testowanie endpointów z poziomu przeglądarki bez użycia zewnętrznych narzędzie tj. postman.

Jako baza danych posłuży SQL Lite i połączymy się z nią za pomocą Entity Framework Core, który pozowali w bardzo łatwy sposób przejść później na np. Postgres lub MS SQL

Na koniec pokażę Ci jak stworzyć dockerfile aby uruchomić aplikację w kontenerze linuxowym – Docker.

Warsaw Stops API

Tutorial powstał w .NET Core 2.0. Stworzyłem repozytorium, w którym każdy kolejny brancha to jeden krok. Starałem się abyś mógł zrobić checkpointa na koniec każdego kroku.

Aplikację hostuję pod adresem http://warsaw.sebcza.pl/swagger
Jeżeli chciałbyś, wykorzystać ten backend do projektu open source, projektu na studia, czyli w celach nie komercyjnych to daj znać. Dostosuje go do Ciebie oraz odpowiednio zabezpieczę.

Krok 1 – Wygenerowanie projektu za pomocą dotnet CLI

  • Stwórz nowy katalog dla projektu
  • Wejdź do katalogu
  • Stwórz projekt WebAPI wpisz w konsole 
dotnet new webapi
Checkpoint: https://github.com/sebcza/warsaw-stops/tree/01-empty-web-api  

Krok 2 – Swagger

Dodaj paczkę nugeta dla swaggera. Wpisz w konsole

dotnet add package Swashbuckle.AspNetCore --version 2.2.0

Zarejestruj service swaggera. Dodaj w Startup.cs w ConfigureServices

Skonfiguruj swaggera. Dodaj w Startup.cs w Configure.

Uruchom aplikację poleceniem:

dotnet run

Zobacz rezultat: http://localhost:5000/swagger

Polecenie dotnet-new-api powinno wygenerować przykładowy controller ValuesController. Powinieneś/aś móc go zobaczyć oraz przetestować w Swaggerze.

Chekpoint: https://github.com/sebcza/warsaw-stops/tree/02-swagger 

Krok 3 – baza danych oraz Entity Framework Core

Stwórz folder Models w głównym katalogu aplikacji

W folderze Models stówrz nową klase Stop w pliku Stop.cs

Dodaje Entity Framework Core Sqlite do projektu. Wpisz w konsole:

dotnet add package Microsoft.EntityFrameworkCore.Sqlite --version 2.0.2

Wykonaj w terminalu: dotnet restore

Stwórz DbContext. Dodaj w głównym katalogu aplikacji plik WarsawDbContext.cs a w nim klasę WarsawDbContext, która dziedziczy po DbContext.

Dodaj ConnectionString dla Sqlite w appsettings.json

"ConnectionStrings": { "WarsawDbConnection": "Data Source=WarsawDB.db" }

Zarejestruj WarsawDbContext w kontenerze DI oraz przekaz connections string. W pliku Startup.cs w ConfigureServices dodaj:

Dodaj CLI Entity Framework aby móc dodawać migracje. W pliku WarsawCore.csproj w sekcji „ItemGroup” dodaj:

<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />

Wykonaj: dotnet restore

Dodaj migracje tworzącą tabelę Stops w bazie danych. Wykonaj:

dotnet ef migrations add "Create Stop table"

Stwórz bazę danych. Wykonaj:

dotnet ef database update

EF oraz baza są gotowe do użycia

Checkpoint: https://github.com/sebcza/warsaw-stops/tree/03-entity-framework 

Krok 4 – Repozytorium

W tym kroku wprowadzimy już trochę logiki do naszej aplikacji. Aplikacja mobilna/webowa to tabela wszystkich przystanków z paginacją oraz wyszukiwarką. Wyszukiwarka wyszukuje po nazwie przystanku. Wynik wyszukiwania zawęża tabelę poniżej. W tabelki nie są widoczne wszystkie dane. Tylko, te które pozwalają zidentyfikać przystanek. Reszta danych dostępna jest w widoku szczegółowym.
Oprócz tego użytkownik powinień mieć możliwość dodawania, usuwania oraz modyfikowania przystanku.

Dzięki tym wymaganiom możemy teraz zaprojektować repozytorium, czyli warstwę danych.

Stwórz folder Repositories w głównym katalogu projektu. A w nim interfejs IStopsRepository oraz klasę StopsRepository

Zarejestruj Repozytorium jako serwis aby móc go wstrzykiwać. Dodaj w Startup.cs w ConfigureServices

Checkpoint: https://github.com/sebcza/warsaw-stops/tree/04-repository 

Krok 5 – Controller

Na początek przyda się kila nowych modeli, które będą reprezentować request oraz response.

W katalogu Models Utwórz plik CreateStopRequest.cs a w nim klase.

Uwórz plik GetStopRequest.cs w Models a w nim klase

Utwórz plik SearchResult.cs w Models a w nim klasy

Teraz pora na controller a w nim dwie metody GET jedna do wyciagania pojedyńczego przystanku po id oraz druga do wyszukiwania przystanku po fragmencie nazwy. Controller zawiera równieź metody do usuwnia, modyfikowania oraz dodawania przystanków a więc mamy pełnego CRUD’a.

Utwórz plik StopsController.cs w Controllers a w nim:

Usuń ValuesController.cs

Checkpoint: https://github.com/sebcza/warsaw-stops/tree/05-controllers 

Krok 6 – Dokeryzacja

FROM microsoft/aspnetcore-build:2.0 AS build-env
WORKDIR /app

# Copy csproj and restore as distinct layers
COPY *.csproj ./
RUN dotnet restore

# Copy everything else and build
COPY . ./
RUN dotnet publish -c Release -o out
COPY WarsawDB.db ./out/

# Build runtime image
FROM microsoft/aspnetcore:2.0
WORKDIR /app
COPY --from=build-env /app/out .
ENTRYPOINT ["dotnet", "WarsawCore.dll"]

Dodaj plik w głównym katalogu projektu .dockerignore:

bin\
obj\

Wykonaj aby zbudować obraz konternera:

docker build -t warsawapp .

Wykonaj aby stworzyć i uruchomić kontener

docker run -d -p 8080:80 --name MojaNazwaKontenera warsawapp

Kontener został stworzony. Twoja aplikacja działa teraz na porcie 8080 w kontenerze dockerowym.

Checkpoint: https://github.com/sebcza/warsaw-stops/tree/06-docker 

Baza wiedzy