Blog Dla Młodszych Programistów C#/.NET

wtorek, 25 października 2022
W ASP.NET Core oprócz tworzenia typowych aplikacji MVC, możemy również tworzyć REST API. Jest mnóstwo zasad o których w takim przypadku musisz pamiętać, tak aby Twoje aplikacje były chętnie używane przez klientów. Takie REST API na pewno często będziesz pisał w swojej karierze, idealnie może nadać się np. jako backend do aplikacji SPA, ale nie tylko. Tworząc takie aplikację warto pamiętać o wszystkich najlepszych praktykach. W tym artykule przedstawię Ci właśnie 6 najlepszych praktyk tworzenia aplikacji webowych w ASP.NET Core REST API, dzięki której Twoje api będzie spełniało wszystkie wymagania.

6 Najlepszych Praktyk w ASP.NET Core REST API

1. Akcje powinny zwracać odpowiednie typy i kody


Zgodnie z konwencją akcje kontrolerów REST API powinny typy i kody. Akcje z kontrolerów mogą zwracać typ IActionResult i w zależności od tego jaka jest odpowiedź odpowiedni kod.

Kody HTTP:
  • 100-199 odpowiedź informacyjna
  • 200-299 sukces
  • 300-399 przekierowanie
  • 400-499 błąd klienta
  • 500-599 błąd serwera
Najczęściej używane kody HTTP:
  • 200, 201, 204
  • 301
  • 400, 401, 403, 404, 405
  • 500
Wszystkie te kody możemy zwracać w ASP.NET REST API.


2. Stosuj odpowiednie atrybuty dla akcji


W REST API mamy kilka typów metod. Natomiast 4 najczęściej stosowany to metoda GET, POST, PUT oraz DELETE. W ASP.NET Core dzięki atrybutom, które umieszczamy nad nazwą akcji możemy prawidłowo oznaczać jej typ.

Dla akcji GET będzie to [HttpGet].
Dla akcji POST będzie to [HttpPost].
Dla akcji PUT będzie to [HttpPut].
Dla akcji DELETE będzie to [HttpDelete].


3. Stosuj odpowiednie nazewnictwo dla endpointów


Pamiętaj, aby stosować odpowiednie nazewnictwo dla endpointów rest api. To znaczy stosujemy tutaj tylko rzeczowniki bez żadnych czasowników.

Poprawne endpointy/adresy URL:
  • GET /users (pobieranie użytkowników)
  • GET /users/10 (pobieranie użytkownika)
  • POST /users (dodawanie użytkownika)
  • PUT /users (aktualizowanie użytkownika)
  • DELETE /users (usuwanie użytkownika)
  • DELETE /users/role (usuwanie roli użytkownika)
Najlepiej w takim przypadku tworzyć kontrolery dla WEB API z nazwą w liczbie mnogiej. Wtedy można prosto zbudować właśnie takie endpointy.

Natomiast nie powinno się tworzyć endpointów widocznych poniżej.

Niepoprawne endpointy/adresy URL:
  • GET /getUsers
  • GET /getUserById/10
  • POST /users/addUser
  • PUT /updateUser
  • DELETE /delete/user
Tylko tutaj opisujemy nazwy endpointów, z kolei same nazwy akcji w kontrolerach mogą już mieć inne nazwy i tutaj możesz stosować już czasowniki.


4. Umożliwiaj klientowi stosowanie paginacji, sortowania i filtrowania danych


Pamiętaj, że gdy udostępniasz listę jakichś danych przez REST API, to warto dostosować ją tak, aby klient mógł pobrać tylko takie dane, których faktycznie potrzebuje. To znaczy, stwórz akcję tak, aby na podstawie przekazanych do niej parametrów klient mógł zastosować od razu paginację i mógł pobrać np. tylko dane z wybranej strony, a nie wszystkie dane z bazy danych. Tak samo zezwól mu na sortowanie i filtrowanie danych po różnych właściwościach. Dzięki temu całą aplikacja będzie działała dużo szybciej i będzie mogła zostać poprawnie zoptymalizowana.

public class MethodParameters
{
    public int PageNumber { get; set; }
    public int PageSize { get; set; }
    public string SearchTerm { get; set; }
    public string OrderBy { get; set; }
}
Najlepsze Praktyki w ASP.NET Core REST API - paginacja


5. Wersjonuj API


Tworząc REST API już od początku zaprojektuj je tak, aby możliwe było wersjonowanie. To znaczy chcemy udostępniać użytkowniki różne akcje, endpointy w jednym czasie pod różne wersje. Warto aby aktualizacja REST API nie popsuła działania aplikacji klienckich, które używają np. starszej wersji naszego API. W ASP.NET Core wersjonowanie jest jak najbardziej wspierane, dlatego warto z tego korzystać. Wystarczy tylko kilka linii konfiguracji i nasze API będzie tworzone zgodnie z dobrymi zasadami.

https://localhost/api/v1/users
https://localhost/api/v2/users
https://localhost/api/v3/users
https://localhost/api/v4/users


6. Używaj Swaggera


Swagger jest również wspierany przez ASP.NET Core i jeżeli przy tworzeniu nowego projektu ASP.NET CORE REST API zaznaczymy odpowiedni checkbox, to automatycznie swagger z domyślną konfiguracją zostanie dodany do naszej aplikacji. Dzięki niemu możemy od razu tworzyć dokumentację REST API i umożliwić innym programistą, którzy będą używać tego API łatwiejsze jego testowanie. Warto dodać Swaggera do każdego projektu, bardzo ułatwia życie programiście.

Najlepsze Praktyki w ASP.NET Core REST API - swagger

Szkoła ASP.NET Core


Jeżeli interesują Cię tematy z tworzeniem profesjonalnych aplikacji webowych w ASP.NET Core, to rozważ dołączenie do: Szkoły ASP.NET Core. Jest to zaawansowane praktyczne szkolenie ASP.NET Core MVC + REST API dla Programistów C#/.NET. Szkolenie składa się z 14 rozbudowanych modułów. W szkoleniu tworzymy kompletną aplikację w ASP.NET Core od pierwszych linii kodu, aż po wdrożenie w chmurze (więcej tutaj).

To wszystkie na dzisiaj. Jeżeli taki artykuł Ci się spodobał, to koniecznie dołącz do mojej społeczności – darmowe zapisy, gdzie będziesz również miał dostęp do dodatkowych materiałów i przede wszystkim bonusów. Do zobaczenia w kolejnym artykule.

Poprzedni artykuł - 12 Najlepszych Praktyk w ASP.NET Core MVC
Autor artykułu:
Kazimierz Szpin
Kazimierz Szpin
CTO & Founder - FindSolution.pl
Programista C#/.NET. Specjalizuje się w Blazor, ASP.NET Core, ASP.NET MVC, ASP.NET Web API, WPF oraz Windows Forms.
Autor bloga ModestProgrammer.pl
Komentarze (2)
toit
TOIT, sobota, 5 listopada 2022 21:04
Poszukuję dość prostego język o składni podobnej do C#, ale open source bez telemetrii korporacji. Patrzyłem już na Rust, ale ma brzydką składnię, a Zig i Odin mają wskaźniki. Roc, Toit, Gleam są chyba mało popularne. Zostaje tylko D i Vala?
Kazimierz Szpin
KAZIMIERZ SZPIN, niedziela, 6 listopada 2022 08:08
Cześć @TOIT. Sam jestem wielkim zwolennikiem C# i zdecydowanie polecę Ci ten język. Rozwijam się w nim od ponad dekady i z roku na rok jest coraz lepszy - także moim zdaniem, to jest najlepszy wybór :)
Dodaj komentarz

Wyszukiwarka

© Copyright 2024 modestprogrammer.pl. Wszelkie prawa zastrzeżone. Regulamin. Polityka prywatności. Design by Kazimierz Szpin