REST API - jeden generyczny endpoint, czy kilka mniejszych dedykowanych

Witam,

chciałbym zapytać co w Waszym przekonaniu jest lepszym rozwiązaniem, jeden generyczny endpoint API, czy kilka konkretnych.

Rozważmy sytuację, nasza firma obsługuje placówki szkolne: SchoolAbc, SchoolDef, SchoolXyz.
Potrzebujemy wystawić API do dodawania uczniów do szkoły (API wewnętrzne tylko i wyłącznie dla frontu, który jest tworzony przez naszą firmę). Każda z tych placówek oczywiście ma swoją logikę i oczekuje innych danych dotyczących uczniów:

• SchoolAbc: FirstName, LastName, Pesel
• SchoolDef: FirstName, LastName, BirthDate,
• SchoolXyz: FirstName, LastName, Pesel, Address, PhoneNumber etc...

Każda z placówek ma też inną walidację, czyli np. SchoolAbc pozwala na dodanie ucznia, jeśli ten nie ukończył 20 roku życia itd.
Do tej pory wystawiałem osobne endpointy dla każdej z placówek czyli:

• /api/school/abc/students
• /api/school/def/students
• /api/school/xyz/students

Każdy z endpointów przyjmował w body inne parametry, które następnie trafiały do dedykowanego placówce command handlera, który był odpowiedzialny za realizację useCase'a (walidacja + wykonanie command'a).
Wydaje mi się to naturalne, natomiast lider mojego zespołu chciałby żeby to wszystko było realizowane przez jeden generyczny endpoint np.

• /api/students

Czyli przesyłam dane, a następnie dopiero w handlerze, za pomocą fabryki mam zmapować generyczny request na request dedykowany dla konkretnej placówki i wywołać klasę obsługującą logikę odpowiedniej szkoły. Nie widzę zalet takiego rozwiązania, ok jest jeden endpoint, ale to wcale nie znaczy, że jest mniej pracy. W tym przypadku również muszę zaprogramować logikę dla konkretnej szkoły, a dodatkowo dochodzi mi konieczność przemapowania requestów. Odnoszę też wrażenie, że kod staje się też mniej czytelny, jak i samo API.

Co Wy o tym sądzicie?

Pytanie brzmi ile i jak skomplikowane requesty chcecie obsługiwać. To co piszesz z podziałem na endpointy ma sens jak macie te 2-3 opcje. Co jak będzie ich 10 albo 100? ;)
Rozwiązanie z jednym endpointem to coś na wzór np. API elasticsearcha (wyobraź sobie obsługe query do elastica za pomocą róznych endpointów ;) ).
Może warto pomysleć o czymś w stylu graphql w waszym przypadku? To też taka opcja gdzie jest jeden endpoint, ale jednak format zapytań jest "ustandaryzowany"

edit: dla jasności, ja nie staje po żadnej ze stron bo nie znam twojej domeny, ale widać ze jesteś nastawiony na nie do tej opcji z jednym endpointem więc chciałem tylko zasygnalizować że to czasem ma sens :)

Na chwilę obecną są to 4 opcje, natomiast za 2 lata może ich być np. 10. Jeśli chodzi o skomplikowanie, to najprostszy request ma 4 parametry, a najbardziej złożony 18. Możemy założyć, że w takim przedziale będzie się utrzymywać liczba parametrów dla pozostałych placówek szkolnych.

Front, różne potrzeby co do zwracanych wyników. Pierwsze co pomyślałem to graphql.

Jak konsultant odpowiem "to zależy".

Jak dobry konsultant spróbuję wyjaśnić od czego. ;-)

Moim zdaniem powinniście pogadać w zespole i wybrać opcję wam najbardziej pasującą.
Opcja z 1 endpointem jest najbardziej RESTowa... ale REST nie jest jedyną słuszną drogą. Zwłaszcza jak wy nie tworzycie dla kogoś API tylko dla własnego frontendu. Kwestia też tego jak to łątwiej ogarnąć na frontendzie bo gdzieś będzie jakaś logika że jak szkoła X to wysyłam ABC, a jak Y to wysyłam FGH. Ale pewnie i tak i siak front musi o tym wiedzieć co wysłać? A może nie... Nie wiem. Ty wiesz (albo ludzie u Ciebie).
Opcja z dedykowanym endpointem zapewnia łatwiejsze obsługiwanie/przepychanie requestu, bo każdy ma swój dedykowany i od razu wiadomo powinno być co który endpoint wymaga. Zależnie od technologii może to też uprościć podstawową walidację, np jeśli wiek się nie zgadza można to od razu ogarnąc adnotacją i framework się zajmie resztą, Ale znów nie wiem co, jak i w czym walidujecie, to może ale nie musi ułatwić życie.
Fakt faktem, że jak jak będzie ich 10 to... będzie ich 10. Albo będzie logika skomplikowana jak z 1 generycznego requestu zrobić niegeneryczny i gdzie go upchać ( przesadzam ze skomplikowaniem, wystarczy Enum z wartością per szkoła i to po jego wartości decydujemy gdzie ten request idzie dalej, ale trochę kodu mapującego jest do zrobienia ekstra).

Kolejny argument który może się pojawić: "A jak trzeba będzie dodać szkołę to ktoś musi dodać nowy endpoint, kod napisać... "No tak, ale trzeba będzie ten kod napisać zawsze, zakodować przerzucenie z generyka do właściwego handlera. Także zero zysku tutaj.
Za to może ale nie musi być zysk na frontendzie, zależnie co on wie i jak jest napisany, że tam nie trzeba nic dodawać i od ręki obsłuży nową szkołę, a w wypadku osobnego endpointu, trzeba front zaktualizować. Ale znów, jeśli i tak trzeba to zrobić...

Dla Twojej sytuacji myślę, że warto zainteresować się GraphQL

+1 do generycznego endpointu a la ElasticSeach