Graph API

Graph API to interfejs programistyczny umożliwiający integrację aplikacji z usługami ekosystemu danej platformy.

Model danych stojący za nazwą Graph API

Graph API to interfejs programistyczny, w którym zasoby systemu przedstawia się jako obiekty połączone relacjami. Obiektem może być na przykład użytkownik, plik, wiadomość, urządzenie albo wydarzenie, natomiast relacją będzie członkostwo, autorstwo, przynależność do folderu lub udział w spotkaniu. Aplikacja nie musi znać wewnętrznej budowy usługi. Odczytuje obiekty oraz przechodzi do powiązanych z nimi danych za pomocą zdefiniowanych punktów dostępu.

W praktyce określenie Graph API nie oznacza jednego, uniwersalnego produktu. Jest nazwą stylu projektowania interfejsu, stosowanego przez różne platformy. Konkretna implementacja może udostępniać żądania HTTP, dane w formacie JSON, mechanizmy filtrowania oraz paginację, ale dokładne adresy zasobów, nazwy pól i dostępne operacje zależą od dokumentacji danej platformy. Dlatego kod przygotowany dla jednego Graph API nie jest automatycznie zgodny z innym interfejsem o podobnej nazwie.

Obiekty, relacje i zapytania w interfejsie

Typowe żądanie Graph API wskazuje zasób główny, a następnie może odwoływać się do jego właściwości lub relacji. W interfejsach opartych na HTTP operacja GET służy zwykle do pobierania danych, POST do utworzenia obiektu albo wykonania określonej operacji, PATCH do częściowej zmiany, a DELETE do usunięcia zasobu, jeśli dana platforma na to zezwala. Takie znaczenie metod wynika z konwencji HTTP, lecz każda usługa może wprowadzać własne ograniczenia.

Odpowiedź często zawiera obiekt JSON z identyfikatorem, właściwościami oraz odnośnikami do kolejnych danych. Przy większych zbiorach wynik może być dzielony na strony. Aplikacja powinna wtedy obsłużyć wskaźnik następnej strony zamiast zakładać, że pierwsza odpowiedź zawiera wszystkie rekordy. Istotne są także kody odpowiedzi HTTP: kod 200 oznacza poprawne wykonanie żądania, 201 utworzenie zasobu, 204 odpowiedź bez treści, 401 brak prawidłowego uwierzytelnienia, 403 brak uprawnień, a 404 nieznalezienie wskazanego zasobu. Konkretne API może stosować dodatkowe kody i własny format błędów.

Uwierzytelnianie, uprawnienia i obsługa błędów

Graph API zwykle rozdziela uwierzytelnianie od autoryzacji. Uwierzytelnianie potwierdza, kto wysyła żądanie, a autoryzacja określa, do jakich obiektów i operacji ta aplikacja ma dostęp. W wielu usługach internetowych spotyka się tokeny dostępu przekazywane w nagłówku HTTP Authorization, często w schemacie Bearer. Token może mieć ograniczony czas ważności i określony zakres uprawnień. Nie należy utożsamiać samego posiadania tokenu z prawem do odczytu wszystkich danych platformy.

Poprawna integracja musi przewidywać wygaśnięcie tokenu, odmowę dostępu, brak zasobu, błędne parametry oraz ograniczenie liczby żądań. Niektóre usługi odpowiadają błędem 429 Too Many Requests, gdy aplikacja wysyła zapytania zbyt często. Klient powinien wtedy respektować informacje o czasie ponowienia, jeśli są przekazane, oraz stosować kontrolowane ponawianie żądań. Ważne jest również rejestrowanie adresu zasobu, metody, kodu odpowiedzi i identyfikatora błędu bez zapisywania w logach pełnych tokenów dostępu.

Graph API w praktycznej diagnozie aplikacji komputerowej

Problemy z Graph API mogą wyglądać jak awaria laptopa, programu pocztowego lub synchronizacji plików, chociaż ich przyczyną bywa nieprawidłowy token, wygasła sesja, błędny adres usługi, niedostępne połączenie sieciowe albo odrzucone uprawnienie. Diagnoza powinna rozdzielać warstwę sprzętową od programowej: najpierw sprawdza się stabilność systemu i połączenia, następnie komunikat aplikacji, kod odpowiedzi HTTP oraz moment wystąpienia błędu. Samo ponowne uruchomienie programu nie wyjaśnia, czy problem dotyczy komputera, konta, konfiguracji czy zewnętrznej usługi.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów, komputerów PC i ich podzespołów, a przy problemach z aplikacją można przeanalizować objawy, konfigurację systemu oraz komunikaty wskazujące na błędną komunikację z interfejsem. Przydatne są dokładna treść błędu, nazwa programu, data wystąpienia problemu i informacja, czy błąd pojawia się na jednym urządzeniu, czy na kilku. Takie dane pomagają odróżnić lokalną usterkę oprogramowania od problemu po stronie konta lub usługi, bez przypisywania awarii samemu pojęciu Graph API.