6 Najlepszych Praktyk w ASP.NET Core REST API

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

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