Czy podczas tworzenia interfejsu API powinienem trzymać się małych funkcji i wielu połączeń, czy też kilku połączeń i dużych funkcji?

Mam platformę szynową, którą utrzymuję. Ma na nim wiele różnych aplikacji internetowych. Jednak teraz klient prosi o interfejs API, aby mógł zatrzymać użytkowników w swojej witrynie, ale skorzystać z niektórych naszych zautomatyzowanych zadań.

Platforma służy do tworzenia aplikacji ubezpieczeniowych i umożliwia ich zakup online, a także zapewnia sposoby pobierania dokumentacji związanej z polisą.

Tak więc moje pytanie podczas tworzenia interfejsu API brzmi:

Kiedy muszę zrobić wiele rzeczy, na przykład validate, utworzyć user, user profilei policy, prawie w tym samym czasie. Powinienem wykonać 4 osobne wywołania API i sprawić, aby klient zbudował 4 wywołania po swojej stronie. LUB czy powinienem mieć jedno wywołanie, które wyklucza wiele parametrów, które weryfikuje klienta i tworzy wszystkie 3 te rzeczy jednocześnie, upraszczając rzeczy dla klienta?

Klient, w tym przypadku, otrzymuje wszystkie wymagane informacje w tym samym czasie, więc nie jest tak, że w ich aplikacji występuje naturalny przepływ, w którym zatrzymuje się i może wykonać połączenie API z moją platformą.

Po wcześniejszym korzystaniu z wielu interfejsów API po stronie klienta, moim zadaniem jest uczynienie tego tak prostym dla klienta, jak to tylko możliwe, i umożliwienie mu wykonania tylko jednego połączenia. Prowadzi to jednak do dość dużego functionsinterfejsu API, którego nie jestem fanem.

Jak sugerujesz, żebym sobie z tym poradził?

Uwaga: nie jestem zbyt pewny, czy klienci mogą wdrożyć skomplikowane API po swojej stronie.

Co powiesz na zrobienie obu? Mają „ niskopoziomowy ” (że tak powiem) interfejs API, który udostępnia funkcje systemu, i mają inną „warstwę”, która udostępnia usługi, które klient może chcieć wykonać. Ta warstwa użyłaby wymaganych wymaganych interfejsów API niskiego poziomu, ale są one nadal widoczne, jeśli klient tego chce.

AKTUALIZACJA: Aby uwzględnić niektóre świetne uwagi i komentarze innych.

1. Zastanów się, czy klient będzie kiedykolwiek musiał wywoływać jedną z mniejszych metod API, np. Czy możliwe jest wywołanie createUserProfile bez wywoływania createUser? Jeśli nie, nie ujawniaj tej metody. Dzięki NoobsArePeople2

2. Prosty, ale doskonały punkt. Kluczowy problem z ujawnieniem czegoś w interfejsie API - nigdy nie można tego odkryć. Ujawnij minimum niezbędne do funkcjonowania, a następnie rozwiń zamiast eksponować wszystko i ... cóż, wtedy jego nagie i wprowadzanie zmian może być krępujące i niezręczne . Dzięki MichaelT

Myślę, że patrzysz na to w niewłaściwy sposób. Nie martw się o duże | małe rozmowy lub wiele | kilka połączeń.

Pomyśl o obiektach biznesowych i działaniach, które można wykonać za pomocą | dla | przeciwko tym przedmiotom.

Masz:

• Użytkownicy
• Zasady
• Stawki
• ...

Powinieneś więc tworzyć wywołania API wokół tych obiektów.

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

Chodzi o to, aby tworzyć operacje atomowe lub prawie atomowe w oparciu o obiekty biznesowe i ich działania. Uprości to projektowanie i kodowanie - wywołania, które robią to, co powinien zrobić obiekt biznesowy, które pasują do modelu mentalnego lub oczekiwań programistów. Gdy programiści lub architekci omawiają wymagania z analitykami biznesowymi, wszyscy mogą stosować tę samą terminologię i ogólny przebieg operacji.

Problemem w przypadku większych połączeń typu „wszystko w jednym” jest ryzyko wystąpienia działań niepożądanych. Jeśli Policy.Create również spawnuje użytkownika i wyzwala inne działanie, to przerwałoby oczekiwania programistów. Podobnie wiele małych wywołań zmusza programistę do zapamiętania wywołania A, a następnie B, a następnie C w celu wykonania „pojedynczej” operacji biznesowej.

A jak nazwiesz połączenia, będzie zależeć od tego, co będą obsługiwane Railsy i obsługiwane przez Ciebie usługi sieciowe.

Aby być bardziej nakazowym, utworzy to niektóre połączenia, które przyjmują wiele parametrów i mogą mieć wiele wywołań na zapleczu, które są ukryte dla klienta. Skończysz również z dość szybkimi / prostymi wywołaniami, w których API jest niewiele więcej niż opakowaniem podstawowej procedury.

Myślę, że masz dobre przeczucie - zrób interfejs API prosty dla konsumentów. W pewnym stopniu taka jest filozofia umów kierowanych przez konsumentów .

Mówiąc dokładniej, interfejs API powinien ujawniać odpowiednie biznesowe zastosowania. Zastanów się nad dostępną domeną biznesową - czy naprawdę potrzebujesz tych funkcji niskiego poziomu? Jaka jest wada ich kapsułkowania? Duże funkcje interfejsu API same w sobie nie stanowią problemu. Problemem byłoby, gdyby duża funkcja sekwencjonowała operacje, które mogą wymagać podziału na partycje, aby umożliwić interwencję konsumenta.

Osobiście lubię interfejsy API, które:

1. są zoptymalizowane w sposób umożliwiający łatwe wykonanie typowych przypadków użycia
2. wywołania związane z operacjami CRUD są zorientowane wsadowo lub mają wersje wsadowe
3. umożliwia refleksję (aby osoby piszące wtyczki lub powiązania dla innych języków komputerowych mogły zautomatyzować proces)