Zawartość
- Odrób pracę domową
- Bądź konsekwentny
- Użyj OAuth
- Zacząć wcześnie
- Napisz dobrą dokumentację
- Rozwój API: Keep It Simple
Na wynos:
Twórcy oprogramowania chcą sposobu na zintegrowanie swojego oprogramowania z twoim - i nie chcą, żeby wszystko się zepsuło. W tym miejscu pojawia się interfejs 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 miejscu pojawia się interfejs API (interfejs programowania aplikacji). W tym artykule mam nadzieję podkreślić pięć kroków, które można wykonać, aby utworzyć 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.
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 przypadku wywołania wywołanego interfejsu API. W przypadku danych wyjściowych upewnij się, że używasz wspólnych układów struktury danych. Jeśli zawijasz dane wyjściowe jednego wywołania API w a
Powszechną praktyką jest umieszczanie pewnego rodzaju flagi statusu w danych wyjściowych, które wracasz 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 na serwerze 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.
Kolejną 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 już, 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ąć źle udokumentowany interfejs API i dowiedzieć się, jak powinien on 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.