Tworzenie endpointów API w Symfony z API Platform

Wstęp

W dzisiejszym dynamicznym świecie technologii, rozbudowane i złożone aplikacje internetowe są coraz częstsze. Zrozumienie koncepcji związanych z API (Application Programming Interface) staje się kluczowe. Niniejszy artykuł ma na celu wyjaśnienie celu wystawiania endpointów API w naszej aplikacji oraz przedstawienie praktycznych przykładów ich wykorzystania. Artykuł ten jest częścią serii publikacji, w której krok po kroku pokażemy, jak stworzyć aplikację frontendową korzystającą z danych dostarczanych przez nasze API.

Endpointy API to punkty dostępu umożliwiające komunikację pomiędzy aplikacjami, wymianę informacji oraz przetwarzanie danych. Wprowadzanie API pozwala na udostępnianie funkcji naszej aplikacji innym systemom, zwiększając elastyczność i skalowalność naszego rozwiązania. Mówiąc prościej, API to most łączący naszą aplikację z innymi platformami, ułatwiając współpracę w realizacji wspólnych zadań.

W poprzednich artykułach tej serii, stworzyliśmy aplikację w oparciu o framework Symfony, która udostępnia następujące trasy:

1. app_person: /person
2. app_person_create: /person/create
3. app_person_edit: /person/{id}/edit
4. app_person_delete: /person/{id}/delete

Teraz zajmiemy się instalacją API w naszej aplikacji Symfony, a także przedstawimy trasę /api/docs, która pozwoli na łatwe zarządzanie i eksplorację naszego API.

Instalacja API Platform w projekcie Symfony

Aby zintegrować API z naszą aplikacją Symfony, będziemy korzystać z pakietu API Platform. API Platform to zestaw narzędzi, który ułatwia tworzenie i utrzymanie nowoczesnych API. W celu zainstalowania tego pakietu, wystarczy użyć polecenia composer, który jest menedżerem zależności dla PHP:

composer require api

Po zainstalowaniu pakietu, API Platform zostanie zintegrowane z naszą aplikacją Symfony, co pozwoli nam na łatwe tworzenie i zarządzanie endpointami API. Jednym z dostępnych elementów jest interfejs /api/docs, który umożliwia eksplorację naszego API oraz generowanie dokumentacji na podstawie dostępnych endpointów. Interfejs ten bazuje na standardzie OpenAPI, który jest szeroko stosowany w branży.

Kiedy będziemy gotowi do pracy z naszym API, wystarczy, że odwiedzimy trasę /api/docs w przeglądarce internetowej. Zobaczymy wtedy interaktywną dokumentację naszego API, która przedstawia dostępne endpointy, metody HTTP, parametry zapytań oraz przykładowe odpowiedzi. Dzięki temu narzędziu możemy szybko i łatwo zrozumieć strukturę naszego API oraz przetestować jego działanie.

Tworzenie defaultowych endpointów API dla modelu

Aby rozpocząć tworzenie endpointów API w naszej aplikacji Symfony, musimy dodać anotację #[ApiResource] do pliku Entity/Person.php. Anotacja ta pochodzi z pakietu API Platform i pozwala na automatyczne wygenerowanie endpointów dla danej encji. Poniżej przedstawiamy fragment kodu z dodaną anotacją:

use ApiPlatform\Metadata\ApiResource;
// ...
#[ApiResource]
#[ORM\Entity(repositoryClass: PersonRepository::class)]
class Person
{
// ...
}

Po dodaniu anotacji #[ApiResource] do encji Person, zostaną automatycznie utworzone następujące trasy:

1. api/people/{id}{._format}_get: GET /api/people/{id}.{_format} – pozwala na pobieranie szczegółów osoby o danym ID.
2. api/people{._format}_get_collection: GET /api/people.{_format} – pozwala na pobieranie listy osób.
3. api/people{._format}_post: POST /api/people.{_format} – pozwala na dodawanie nowej osoby.
4. api/people/{id}{._format}_put: PUT /api/people/{id}.{_format} – pozwala na aktualizowanie danych osoby o danym ID.
5. api/people/{id}{._format}_patch: PATCH /api/people/{id}.{_format} – pozwala na częściowe aktualizowanie danych osoby o danym ID.
6. api/people/{id}{._format}_delete: DELETE /api/people/{id}.{_format} – pozwala na usunięcie osoby o danym ID.

Każda z tych tras umożliwia wykonywanie określonych operacji na encji Person. Oto krótkie wyjaśnienie ich funkcjonalności:

1. Pobieranie szczegółów osoby (GET /api/people/{id}.{_format}): umożliwia uzyskanie informacji na temat konkretnej osoby na podstawie jej identyfikatora.
2. Pobieranie listy osób (GET /api/people.{_format}): pozwala na wyświetlanie wszystkich osób zapisanych w naszej aplikacji.
3. Dodawanie nowej osoby (POST /api/people.{_format}): umożliwia dodanie nowego obiektu typu Person do naszej aplikacji.
4. Aktualizowanie danych osoby (PUT /api/people/{id}.{_format}): pozwala na modyfikację istniejącej osoby, zaktualizowanie jej danych.
5. Częściowe aktualizowanie danych osoby (PATCH /api/people/{id}.{_format}): umożliwia aktualizację tylko wybranych danych osoby, bez konieczności zmieniania całego obiektu.
6. Usuwanie osoby (DELETE /api/people/{id}.{_format}): umożliwia usunięcie konkretnej osoby z naszej aplikacji na podstawie jej identyfikatora.

Dodanie anotacji #[ApiResource] znacząco upraszcza proces tworzenia API, automatyzując wiele czynności związanych z generowaniem odpowiednich tras i metod. Dzięki temu możemy skupić się na logice biznesowej naszej aplikacji, jednocześnie utrzymując czytelność i elastyczność naszego kodu.

Liczba mnoga API

Warto zwrócić uwagę na fakt, że po dodaniu anotacji #[ApiResource] do encji Person, endpointy zostały automatycznie utworzone z prefiksem /api/people. Wynika to z działania API Platform, które, opierając się na nazwie encji, generuje ścieżki URL zgodne z konwencjami RESTful oraz zasadami tworzenia zasobów w liczbie mnogiej. W przypadku naszej encji o nazwie Person, wygenerowane endpointy otrzymały prefiks /api/people.

Taka metoda tworzenia ścieżek URL jest intuicyjna, a jednocześnie umożliwia łatwe rozszerzanie naszego API o dodatkowe zasoby i funkcje. W przypadku rozbudowanych aplikacji z licznymi encjami, konsekwentne stosowanie tej konwencji ułatwia zarówno proces twórczy, jak i utrzymanie kodu.

Pobieranie danych z endpointu

Po wejściu na trasę /api/people.json, uzyskujemy dostęp do listy osób zapisanych w naszej aplikacji w formacie JSON. Trasa ta korzysta z metody GET i odnosi się do wygenerowanego endpointu _api_/people{._format}_get_collection.

Odpowiedź z serwera będzie zawierać listę obiektów Person przedstawionych jako struktury danych w formacie JSON. Każdy obiekt będzie składał się z atrybutów zdefiniowanych w encji Person oraz wartości przypisanych tym atrybutom.

Przykładowa odpowiedź dla dwóch osób w bazie danych może wyglądać tak:

Stosowanie formatu JSON pozwala na łatwe przetwarzanie danych w różnych częściach aplikacji i w innych systemach korzystających z API. Jego szerokie zastosowanie w komunikacji między aplikacjami wynika z prostoty obsługi, czytelności oraz elastyczności. Format ten ułatwia reprezentację struktur danych, takich jak obiekty, tablice i wartości proste.

Dzięki trasie /api/people.json, mamy możliwość wyświetlania listy osób w aplikacji frontendowej. Możemy filtrować wyniki, sortować je według różnych kryteriów i korzystać z paginacji. Dane w formacie JSON pozwalają na łatwą integrację API z narzędziami analitycznymi, aplikacjami mobilnymi czy usługami trzecich stron.

API Platform oferuje elastyczność poprzez dodawanie dodatkowych formatów, takich jak XML czy CSV. Dostosowanie formatu odpowiedzi do potrzeb klienta można osiągnąć za pomocą parametrów URL lub konfiguracji serwera. W przyszłych artykułach omówimy te zagadnienia oraz inne zaawansowane funkcje API.

Podsumowanie

Podsumowując, artykuł ten przybliża korzyści płynące z użycia formatu JSON oraz możliwości ścieżki /api/people.json. W następnych częściach serii będziemy kontynuować tematykę API, omawiając bardziej zaawansowane aspekty, takie jak dostosowywanie tras, filtrowanie danych, walidacja, paginacja czy zabezpieczanie endpointów. Wszystko to pozwoli nam na pełniejsze wykorzystanie możliwości API Platform i Symfony w tworzeniu nowoczesnych, wydajnych aplikacji internetowych, które będą doskonale współpracować z innymi narzędziami i usługami.