[LR] Budowanie API Opcje

[markonix]

Zabieram się do wystawienia API do istniejącej już aplikacji, API będzie zarówno pod appkę jak i strony www.
Chciałbym aby to było dobre, RESTowe, użyteczne i elastyczne API, a nie kilka sztywnych metod.
Jakieś doświadczenia jak zbudować dobre API, z którego byście sami z przyjemnością korzystali?

Kilka ważnych aspektów:
- autoryzacja
- wersjonowanie
- spójny format błędów
- kontrola nad zwracanymi danymi (zarówno wybór pól jak i relacji)
- limitowanie i paginacja
- możliwość generowanie zaawansowanych metod typu find, search (szukanie po polach za pomocą różnych warunków, które można użyć w where())
- dokumentacja (generator?)

Pod większością względów podoba mi się API wFirmy (system do faktur):
https://doc.wfirma.pl/#h2-Komunikacja-h3-Ko...nie-zapyta-find
Poza troszkę zagmatwanym formatem danych, zwracanych przez te API i brakiem wersjonowania to jest to dla mnie wzór, który chciałbym osiągnąć.

Zastanawiam się czy znajdę gotowy szkielet takiego API czy muszę to implementować wszystko samemu, na poziomie kontrolerów i repozytoriów?
W L5.5 jest kilka dodatków typowo pod API np. Responses ale i tak wciąż jest sporo pracy.

Ten post edytował markonix 26.11.2017, 02:21:48

[r4xz]

Polecam po prostu zapoznać się z panującymi standardami. Jeśli o mnie chodzi to bardzo podobała mi się ta infografika.

Dokumentację polecam robić w swaggerze, po wygenerowaniu wygląda to bardzo dobrze i jest funkcjonalne (do tego jest to już sprawdzone i dosyć dojrzałe rozwiązanie). Sam przykład wykorzystania swaggera w projekcie:

[PHP] pobierz, plaintext 
/**
     * @SWG\Post(
     *     path="/schedules/{schedule_id}/close",
     *     consumes={"multipart/form-data"},
     *     tags={"Schedules"},
     *     security={{"api_key": {}}},
     *     @SWG\Parameter(in="path", name="schedule_id", required=true, type="integer"),
     *     @SWG\Response(response="200", description="Schedule successfully opened."),
     *     @SWG\Response(response="401", description="Unauthenticated."),
     *     @SWG\Response(response="403", description="Invalid permissions."),
     *     @SWG\Response(response="404", description="Schedule with given id not found."),
     *     @SWG\Response(response="409", description="Schedule has been already opened."),
     * )
     */
public function close(Schedule $schedule)
{
    // ...
}
[PHP] pobierz, plaintext 

Oczywiście z tego kodu generuje się ładna dokumentacja, zobacz np. ten przykład. Jest też możliwość generowania klientów dla wielu języków programowania, dzięki temu nikt nie musi się zastanawiać co robi Twoje API, analizować dokumentacji itp. ponieważ ma to w postaci ładnych metod gotowych do użycia (choć wtedy trzeba to trochę łądniej napisać niż w moim przykłądzie).

Co do samej obsługi parametrów field, sort, filter itp. to faktycznie jest to problem, istnieją jakieś rozwiązania dla Laravel jednak nie wszystkie mnie satysfakcjonowały, właściwie to z każdego wydobyłbym coś innego. Swego czasu napisałem nawet bibliotekę która pomaga mi w pisaniu tego typu api (link do githuba). Oczywiście przez to że z niej korzystam to znam kilka słabych stron tej biblioteki, ale niestety ze względu na natłok obowiązków nie doczeka się ona drugiej wersji wcześniej jak w lipcu/sierpniu.

I na koniec, bo nie wiem czy słyszałeś, a tym bardziej myślałeś o GraphQL? Jeśli nie słyszałeś to też zobacz jakie to ma możliwości i podejmij decyzję REST vs GraphQL