5 kroków do stworzenia udanego interfejsu API

Taka jest natura tworzenia oprogramowania. Programiści tworzą oprogramowanie z myślą o użytkownikach końcowych. Wydaje się to dość proste, ale czasami ci użytkownicy są również innymi programistami. Nie potrzebują dla nich rzeczy zepsutych. Nie potrzebują nawet prostoty. Wszystko, czego chcą, to dostęp - sposób na zintegrowanie oprogramowania z ich oprogramowaniem. W tym momencie pojawia się interfejs API (interfejs programowania aplikacji). Mam nadzieję, że wyróżnię pięć kroków, które można wykonać, aby stworzyć udany interfejs API.

Odrób pracę domową

Jeśli chodzi o tworzenie oprogramowania, nikt z nas nie chce wynaleźć koła. W tym momencie prawie wszystkie duże firmy internetowe mają interfejsy API dla swoich programów. Zapoznaj się z tymi interfejsami API i spróbuj wybrać różne decyzje projektowe związane z ich tworzeniem.

Istnieje wiele różnych technologii, ale większość interfejsów API, które zobaczysz, będzie korzystała z interfejsu RESTful lub SOAP. Jeśli zastanawiasz się, którego interfejsu API będziesz używać, sugerowałbym podejście RESTful przy użyciu protokołu HTTP. Jest prostszy niż SOAP, jest obecnie bardziej popularny i łatwiej będzie zacząć korzystanie z oprogramowania opartego na sieci Web.

Bądź konsekwentny

Jedną z rzeczy, które programiści najbardziej cenią, jest konsekwencja. Obejmuje to między innymi adresowalność, argumenty wejściowe, formaty wyjściowe i obsługę błędów.

Podczas korzystania z podejścia RESTful istnieje wiele różnych schematów nazewnictwa URI. Każdy ma swoich zwolenników, więc po prostu wybierz jednego i trzymaj się go. To samo dotyczy struktury wejścia i wyjścia. Większość interfejsów API obsługuje XML i JSON jako formaty wejściowe i wyjściowe. Sugerowałbym obsługę obu, ale wybranie domyślnego formatu.

W przypadku danych wejściowych wymagania dotyczące danych wejściowych powinny być konsekwentnie nazywane i powinny mieć sens w kontekście wywoływanego interfejsu API. W przypadku danych wyjściowych upewnij się, że używasz wspólnych układów struktury danych. Jeśli zawijasz wynik jednego wywołania API w a Tag XML, rozważ zrobienie tego z innymi wywołaniami.

Powszechną praktyką jest umieszczanie pewnego rodzaju flagi stanu w danych wyjściowych wysyłanych z powrotem do klienta. W przypadku korzystania z interfejsu API RESTful należy to zrobić przy użyciu kodów stanu HTTP. Na przykład, jeśli właśnie przetworzyłeś żądanie PUT dla istniejącego obiektu danych, kod statusu HTTP, który podałeś w odpowiedzi, będzie się różnić w zależności od wyniku żądania.

Zamiast arbitralnej flagi wskazującej status połączenia można użyć standardowego kodu stanu „200 OK”, aby wskazać, że żądanie zakończyło się powodzeniem, a kod statusu „400 Złych żądań” może oznaczać, że żądanie było zniekształcony. Istnieje wiele kodów stanu HTTP, których można użyć w różnych sytuacjach.

Użyj OAuth

Większość produktów wymaga uwierzytelnienia użytkownika w celu uzyskania dostępu do chronionych zasobów dla tego użytkownika. Jeśli chodzi o interfejsy API, zmuszanie klienta do gromadzenia poświadczeń użytkownika w celu wysłania go na serwer jest złą praktyką. Tu właśnie wchodzi OAuth.

OAuth zapewnia wiele korzyści w porównaniu z uwierzytelnianiem nazwy użytkownika / hasła innej firmy. Przede wszystkim klient nigdy nie ma dostępu do poświadczeń użytkownika. Użytkownik jest przekierowywany na Twój serwer, gdy się loguje. Po zalogowaniu się do Twojej witryny, on lub ona zostaje przekierowany z powrotem do klienta, gdzie klient otrzyma token dostępu do wykorzystania w przyszłych żądaniach do chronionych zasobów.

Inną ważną zaletą korzystania z protokołu OAuth jest możliwość anulowania dostępu klienta w dowolnym momencie. Jeśli użytkownik zdecyduje, że z jakiegokolwiek powodu nie chce, aby klient miał dostęp do chronionych zasobów w jego imieniu, po prostu przechodzi do utworzonego interfejsu i anuluje dostęp klienta.

Zacząć wcześnie

Jedną z najważniejszych rzeczy, które możesz zrobić, aby Twój interfejs API odniósł sukces, jest rozpoczęcie wcześniej. Kiedy piszesz tę funkcję, aby utworzyć jakiś wpis w bazie danych, śmiało, poświęć trochę czasu i napisz dla niego interfejs API.

Napisz dobrą dokumentację

Nic nie zabija API szybciej niż brak dobrej dokumentacji. Chociaż niektórzy programiści mogą wziąć słabo udokumentowany interfejs API i dowiedzieć się, jak powinien działać, większość nie chce tego robić.

Należy udokumentować każde dostępne wywołanie interfejsu API i podzielić je na kategorie według rodzaju danych, na które działają. Wraz z dokumentowaniem punktów końcowych dla samych wywołań interfejsu API należy systematycznie definiować wymagane i opcjonalne argumenty wejściowe, a także struktury danych wyjściowych. Argumenty wejściowe powinny zawierać wartość domyślną, jeśli taka istnieje, a także wskazywać oczekiwany format danych, taki jak liczba lub łańcuch. Wreszcie każde wywołanie interfejsu API powinno zawierać listę warunków błędów i kodów stanu.

Aby dopełnić dokumentację, pamiętaj o dołączeniu jednego lub dwóch przykładów typowych scenariuszy wejścia i wyjścia dla każdego wywołania interfejsu API.

Rozwój API: Keep It Simple

Choć może się wydawać, że opracowanie interfejsu API jest skomplikowanym przedsięwzięciem, sam pomysł interfejsu API nie jest nową koncepcją i istnieje duża ilość dostępnej dokumentacji na każdy poruszony tutaj temat. Pamiętaj tylko, aby stosować dobre praktyki tam, gdzie możesz je znaleźć, i zapewnić spójny, dobrze udokumentowany interfejs.