Dobre praktyki oraz kryteria jakie powinno spełniać API

0

Witam,
Uczę się .NET core.
Przerobiłem MVC z widokami razor. Teraz chciałbym napisać backend, który będzie udostępniał API z którego front będzie korzystał. Szukam w tym celu materiałów (książek, kursów, poradników) pokazujących jak pisać takie api w ASP.NET core. Chciałbym na starcie od razu uczyć się dobrych praktyk, dlatego szukam materiałów opisujących dobre praktyki i kryteria jakie to api powinno spełniać(HATEOAS?). Na pewno macie już doświadczenie więc proszę was o przysługę- mogliście by polecić jakąś dobrą pozycję do poczytania?

1

HATEOAS to dalszy etap, najpierw skup się na tym, aby urle były zasobami, na odpowiednim użyciu metod HTTP i zwracaniu odpowiedniego formatu danych. No i na dopasowanych kodach odpowiedzi. Jeśli Twoje API po otrzymaniu błędnych danych zawsze będzie zwracało HTTP 400, a nie 500 i klarowny komunikat błędu, to będzie lepsze niż 95% API na świecie.

1

Dlaczego utożsamiać API z HTTP/REST? To jakaś monokultura w głowie.

3

Testy integracyjne dla endpointów to podstawa, a je się bardzo przyjemnie pisze w .net core.

2

TLTR: polecam artykuł RESTful API with .NET Core 3 i książkę Hands On RESTful Web Services with ASP.NET Core 3.

Detale:
Pytanie @Kordoba'y skłoniło mnie do odświeżenia trochę wiedzy na temat projektowania API (pod ASP.NET Core 3). To tak ponieważ pracuję nad starszawą aplikacją, mam trochę (za dużo) doświadczenia z WCF, gRPC, (i już mniej z) SignalR oraz prostymi RESTful API (które na potrzeby wewnętrznego Apigee są opakowane w Swagger'ową dokumentację).
Notatki z akcji 'odświeżenie' :

  1. Warto sobie przypomnieć ogólne praktyki na temat projektowania API
    Zakładam, że pewnie ma jakiś ulubiony artykuł, mi przypadł do gustu: https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design
    Można się spierać o szczegóły, ale IMHO artykuł tenże pozwala sprawnie wspiąć się na poziom 'wiem czego nie wiem' i na co warto zwrócić uwagę projektując API (np. zupełnie zapomniałem o modelu Richardsona)
    Przy okazji wpadłem na artykuł na Dzone: Top REST API Best Practices, ludzi którzy napisali cały kurs na ten temat Ultimate ASP.NET Core 3 Web API - ktoś może brał udział / czytał?

  2. Zweryfikowałem krok pierwszy wyszukując anty-wzorców i sprawdzając czy je rozumiem
    Coś starego z InfoQ: REST Anti-Patterns, przypadkowy blog jakiegoś mądrali: A Pragmatic Take On REST Anti Patterns, od groma samo-promocyjnych artykułów na Medium: REST anti-patterns. Nie jest źle, kumam w miarę o co biega.

  3. Wycieczka do biblioteki i sprawdzenie co tam piszczy w Web API w Core 3 (linki do kodu, nie książek, sorry)
    Kiedyś przeglądałem Modern API Design with ASP.NET Core 2 autor Fanie Reynders, wróciłem, przejrzałem. Dużo szczegółów nie ma, moża sobie odpuścić. Poduczam się teraz TypeScript'a i czytam Hands On RESTful Web Services with TypeScript 3 autorstwa Biharck Muniz Araújo - polecam, dowiedziałem się sporo. Idąc tropem tego tytułu przypadkiem wdepnąłem w Hands On RESTful Web Services with ASP.NET Core 3 autorstwa Samuele Resca. Jestem może w 1/4 (ponieważ weekend nie jest tylko do kodowania) ale już szczerze mogę polecić. To nie jest kolejny 'ASP.NET Core in Action' czy 'Building Microservices with ASP.NET Core', które starają się pokryć cały framework i jeszcze okolice obskoczyć. Jest o czym ma być, API to, API tamto, do rzeczy, na temat. Postaram się dać znać jak już skończę, chętnie też usłyszę opinie innych.
    Przejrzałem też ASP.NET Core 3 and React, takie sobie recepty na życie, intuicja i krytyczne oko a'la @somekind wskazuje, że może to nie są najlepsze praktyki.

  4. Wnioski jaki się nasuwają po weekendzie nauki:
    a) używaj Swashbuckle lub NSwag'a (łatwiej zauważyć błędy, niespójności w projektowanym API, no i je na bieżąco testować / dokumentować)
    b) w kontekście powyższego ActionResult<T> lepiej mi pasuje niż IActionResult (dokumentacja sama się generuje)
    c) w kontekście powyższego, są pewne ograniczenia w stosowaniu DataAnnotations, ale ogólnie da się ich używać, skłaniam się ku 'używaj ich gdzie to ma sens'
    d) używaj analizatorów Use web API analyzers
    e) w kontekście powyższego, dodaj do kontrolerów artybut [ApiController] no i nie rejestruj kontrolerów jako MVC (services.AddControler, a nie services.AddMVC)
    f) zwracaj Ok() a nie JsonResult() nawet jeśli dziś to tylko JSON
    g) używaj problem details (dodanie tego [ApiController] atrybutu w tym pomaga), jest już do tego RFC7807 więc to standard
    coś tam jeszcze miałem w notatkach ale umknęło mi

  5. Czy juź ktoś odrobił za mnie zadanie domowe? brain.ly?
    Używając powyższego zacząłem szukać jakiegoś artykułu, który zawiera powyższe wskazówki (tzn. zgadza się ze mną ;-)
    Przeglądając GitHub trafiłem na repo RestfulAPICore3 - kompatybilna dusza (pewnie się kolega też właśnie uczy ;-) Człek się rozpisał na dev.to RESTful API with .NET Core 3 - pokrywa się z powyższymi wnioskami, dodaje mnóstwo swoich, na 100% warto wziąć pod uwagę. Ale chętnie usłyszałbym komentarze na temat tego artykułu.

1 użytkowników online, w tym zalogowanych: 0, gości: 1