Piszemy REST API

Czas wreszcie, żebym napisał coś więcej o projekcie, nad którym aktualnie pracuje, a mianowicie REST API w .NET Core. W tym wpisie opiszę, co to jest i jak działa REST na przykładzie tworzonej przez mnie aplikacji.

Co to jest REST API?

REST — Representational State Transfer — wzorzec tworzenia architektury aplikacji rozproszonych przy użyciu protokołu HTTP. Jest to umowa jak korzystać z tego protokołu, aby uzyskać dostęp do zasobów będących głównym elementem REST-a.

API — Application Programming Interface — interfejs programistyczny aplikacji.

Z tego wynika, że:

REST API to interfejs programistyczny aplikacji oparty o protokół HTTP umożliwiający zarządzanie zasobami (pobieranie, usuwanie, edycja, tworzenie) przy użyciu plików JSON lub XML oraz żądań HTTP.

Oznacza to, że po wysłaniu określonego żądania HTTP zostaje zwrócony klientowi aplikacji JSON lub XML z zasobami oraz odpowiednim kodem HTTP. W REST korzystamy przede wszystkim z 4 żądań HTTP:

  • GET — do pobierania zasobów
  • POST — do tworzenia zasobów
  • PUT — do edycji zasobów
  • DELETE — do usuwania zasobów

Tyle wiedzy teoretycznej na sam początek wystarczy. Więcej wiedzy będę dostarczał wraz z trwaniem tworzenia aplikacji.

Przykład działania REST-a

I tak o to przechodzimy z teorii do praktyki, którą zaprezentuję na już działających elementach aplikacji. Nie jest tego na razie za wiele, ale musi na razie to wystarczyć.

Żądanie POST

Zacznijmy od tego, że z przeglądarki nie można w bardzo prosty sposób wysłać żądanie POST. W tym przykładzie użyłem do tego Postmana.

Po wysłaniu na adres URL powyżej żądania HTTP z ciałem (body):

zwraca nam odpowiedź HTTP:

Status: 201 (Created)

oraz w nagłówku w Location znajduje się adres, pod którym możemy uzyskać dostęp do zasobu. W naszym przypadku jest to:

Żądanie GET:

Po wpisaniu żądania GET na taki adres:

W odpowiedzi dostałem takie o to „coś”:

Na pierwszy rzut oka można nie zauważyć JSON-a, ale jeżeli sformatujemy sobie tę odpowiedź w taki o to sposób:

to widzimy obiekt będący reprezentacją stworzonego przez nas wcześniej użytkownika.

Tyle do tej pory zaimplementowałem. Użycie pozostałych żądań przedstawię tylko teoretycznie:

Żądanie PUT:

Po wysłaniu na powyższy adres takiego JSON-a metodą PUT:

Serwer powinien zwrócić kod odpowiedzi HTTP 204 – No Content — czyli operacja została wykonana pomyślnie, ale serwer nie ma nic do zwrócenia. Na serwerze zasób powinien zostać zaktualizowany i po użyciu metody GET zwrócić użytkownika ze zmienionymi polami username oraz fullname.

Żądanie DELETE:

Po wysłaniu na powyższy adres żądania DELETE powinien zwrócić kod odpowiedzi HTTP 204 – No Content — czyli operacja została wykonana pomyślnie, ale serwer nie ma nic do zwrócenia. Serwer powinien usunąć użytkownika.

Zakończenie

To wszystko, co chciałem przedstawić w dzisiejszym wpisie. W kolejnych wpisach opiszę kolejne zagadnienia związane z tworzoną przez mnie aplikacją. Kod źródłowy jest dostępny na GitHubie.

Jeżeli dotarliście do tego miejsca, to dziękuję za przeczytanie tego wpisu. Jeżeli macie jakieś pytania albo sugestię piszcie w komentarzach poniżej. Do następnego wpisu, który już nie długo.