[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

[markonix]

O limitowanie mi chodzi o to, że w tym moim repozytorium nie ma w ogóle opcji limit jako tako czyli nie ograniczysz w prosty sposób listy zwróconych obiektów. Oczywiście wszystko na poziomie bazy, na razie nie myślałem o operowaniu na pobranej kolekcji ale już załamany powoli o tym myślałem (bo generalnie wszystkie where, limit, load - można zrobić na kolekcji, a na pewno byłoby to prostsze w osiągnięciu), na szczęście znalazłem ludzkie rozwiązanie.
Jeżeli chciałbym limitować kolekcję to muszę użyć paginacji czyli zupełnie innej metody niż zwykłe all() czy get(). Ta metoda ma już limit i offset ale zamiast kolekcji zwraca obiekt gdzie sama kolekcja ląduje w atrybucie data, a oprócz tego masz jeszcze atrybuty dotyczące paginacji czyli sumaryczna liczba rekordów, link do poprzedniej i następnej "strony" wyników co nawet i w API nawet może się przydać ale nie podoba mi się, że użycie limit powoduje takie duże zmiany w zwracanych danych. O wiele lepsze by było aby limit zostawić w spokoju, a dodać atrybut paginate=10,5, który już użytkownik API świadomie przesyłał i wiedział, że otrzyma zupełnie inny zestaw danych.

Jeżeli Twoja biblioteka ma metodę do zwrócenia jeszcze instancji QueryBuilder to prawdopodobnie też bym mógł jej użyć razem z repozytorium tak jak na przykładzie. Na modelach nie operuje zupełnie w kontrolerach.
Repozytoria u mnie już zwracają kolekcje, nie używam raczej get() czy first() w kontrolerach co też jeszcze lepiej je robi klarownymi.

Ten post edytował markonix 16.12.2017, 17:11:03

[r4xz]

O limitowanie mi chodzi o to, że w tym moim repozytorium nie ma w ogóle opcji limit jako tako czyli nie ograniczysz w prosty sposób listy zwróconych obiektów.

To jak to do tej pory realizowałeś dla zapytań które jednak musiały jakoś ograniczać liczbę wyników?

Jeżeli Twoja biblioteka ma metodę do zwrócenia jeszcze instancji QueryBuilder to prawdopodobnie też bym mógł jej użyć razem z repozytorium tak jak na przykładzie. Na modelach nie operuje zupełnie w kontrolerach.

Tak jak napisałem u mnie to działa trochę inaczej, wpierw trzeba przygotować odpowiedni QueryBuilder który przekazuje się w wywołaniu metody, doklejane są do niego odpowiednie warunki i zwracany wynik. Ty widzę szukasz bardziej czegoś co wpierw doklei Ci wszystkie warunki, zwróci QueryBuilder, a dopiero potem będziesz na nim operował. Takie rozwiązanie ma pewne wady jeśli chodzi o implementację tego jako bibliotekę, ponieważ łatwo o sytuację w której programista wykluczy pola które są potrzebne do złączenia relacji. W swojej implementacji tyle pól ile tylko możliwe staram się już wycinać na poziomie zapytania, jednak jest też pewien mały postprocessing który usuwa np. id (a którego nie mogłem wcześnieje usunąć ponieważ Eloquent nie umiałby powiązać relacji).