BoardGameGeek API

Praca z serwisem sprzed dekady

Pierwsze skrzypce w aplikacji będą grały dane, a właściwie ogrom przeróżnych informacji. Warto zatem zacząć pisanie projektu od obsługi API – dokumentacja tutaj.

 Modele, dostęp do danych

Wgryzamy się w dokumentację, przeglądamy przykładowe wywołania(1, 2, 3) i można zacząć rozrysowywać jak powinny być ustrukturyzowane dane. Podstawowym obiektem w aplikacji będzie oczywiście gra planszowa. Jednakże w zależności od kontekstu przyjmuje ona różne formy – podstawową na stronie z informacjami, ale może także należeć do obecnie popularnych gier czy być elementem kolekcji. API w tych sytuacjach udostępnia obiekty o innych polach, zatem dla prostoty i uniknięcia sprawdzania nullów stworzyłem osobne trzy modele. Ponadto obsługa logów rozgrywek, profili graczy(do szybkiego dodawania z kim graliśmy), wyszukiwanie w bazie BGG gier także wymaga osobnych modeli [przykładowe linki: 1, 2, 3].

ModelsCodeMap
Opcja „Code map” w VisualStudio

Zatem wiemy, że mamy do czynienia z plikami XML, uzyskiwanie kolekcji gracza trochę trwa, linków do instrukcji/zasad brakuje, a przede wszystkim – brak jakiejkolwiek wzmianki o możliwości edycji danych! Hm, można się było tego spodziewać – OAuth powstał w 2006 roku. Czyżbyśmy byli zmuszeni do rezygnacji z jednej z głównych funkcji – edycji kolekcji?

Edycja danych i trochę inżynierii odwrotnej

Tu z pomocą przychodzi Fiddler – narzędzie do m.in. przechwytywania ruchu sieciowego. Odpalamy Fiddlera, konfigurujemy przechwytywanie ruchu HTTPS(warto najpierw zajrzeć tu i tu), odwiedzamy BGG, logujemy się i wykonujemy podstawowe czynności.

rulesRequest
Przykładowe użycie Fiddlera

Żądanie #316 zostaje wysłane podczas wybrania kategorii “Rules” w sekcji “Weblinks” na stronie gry; z nagłówka odczytujemy dokładny link – voilà, dobraliśmy się do linków z instrukcją do gry. Pierwszy sukces!

Spróbujmy teraz zmodyfikować jakieś dane. Przykładowo, żeby zrealizować funkcję dodawania/modyfikowania gry z kolekcji potrzebujemy prześledzić następujący scenariusz.

Wszystkie żądania POST odwołują się do tej samej strony(boardgamegeek.com/geekcollection.php), jednak różnią się parametrami:

  1. Użytkownik odwiedza stronę gry.
  2. Użytkownik wybiera opcję „record information”
  3. Użytkownik zaznacza interesujące go statusy dla danej gry.

W 2. i 3. kroku potrzebny jest nam identyfikator gry w kolekcji gracza(collid). Skąd go pozyskać? Otóż API udostępnia możliwość odwołania się do konkretnej gry w kolekcji za pomocą jej identyfikatora(gameid), który znamy. Wystarczy zatem wykonać odwołanie do:

Jednak niedługo dane jest nam nacieszyć się dobrą passą – by wysyłać zadania POST(edycja danych) do serwera potrzebujemy najpierw zalogować się jako użytkownik. I tu mamy mały zgrzyt, ponieważ musimy zasymulować akcje logowania na stronie– potrzebny nam login i hasło użytkownika. Niestety, inaczej się nie da. Na szczęście, BGG obsługuje protokół HTTPS, czyli nasz kontakt z serwerem będzie bezpieczny. Pozostaje drugi słaby punkt – telefon użytkownika. Jeżeli ma on powierzyć nam swoje dane do logowaniu musimy przechowywać je w bezpieczny sposób, ale o tym w przyszłym poście.

Implementacja

Przy pracy z API najważniejsze będą dwie kwestie: pobieranie danych i ich przetwarzanie. BoardGameGeek udostępnia informacje w postaci plików XML, które można pobrać w C# za pomocą biblioteki HttpClient. Jednakże, przy pobieraniu gracza musimy poczekać na odpowiedź serwera – przy pierwszym zapytaniu otrzymujemy komunikat:

Z nagłówkiem HTTP/1.1 202 Accepted. Dopiero po pewnym czasie(zależnym od rozmiaru kolekcji) otrzymamy zwrotny XML. JAk zatem obsłuzyc takie zachowanie w C#? Skorzystamy z właściwości ContinueTimeout w WebRequest oraz Task.Delay i będziemy powtarzać nasze zapytanie aż do uzyskania odpowiedzi(lub przekroczenia limitów):

Dokumenty XML najwygodniej przetwarzać za pomocą LINQ. Obie te rzeczy są solidnie udokumentowane, wiec podam tylko przykład.

Powyższy plik możemy obsłużyć za pomocą:

Całość kodu źródłowego znajduje się w projekcie BggApi.


Autor: Paweł Rzepiński

Dev-wannabe, pasjonat gier planszowych i zimowego szusowania

2 myśli na temat “BoardGameGeek API”

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Pola, których wypełnienie jest wymagane, są oznaczone symbolem *