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.
createUserProfilebezcreateUser? Jeśli nie, nie wystawiaj go.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:
Powinieneś więc tworzyć wywołania API wokół tych obiektów.
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.
źródło
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.
źródło
Osobiście lubię interfejsy API, które:
źródło