Allegro WebAPI

Interfejs programistyczny platformy Allegro

Wytyczne dla aplikacji

Tutaj znajdziesz wytyczne, dzięki którym Twoja aplikacja spełni oczekiwania Allegro.

Kwestie regulaminowe, strona usługi, uwagi ogólne

  1. Każda aplikacja działająca w oparciu o Allegro WebAPI powinna być zgodna z Regulaminem WebAPI, Regulaminem Allegro oraz polskim prawem.
  2. Usługa Allegro WebAPI jest jedynym zalecanym i wspieranym sposobem dostępu do zasobów i mechanizmów serwisu Allegro. Niepożądane jest parsowanie stron WWW (web scraping), e-maili oraz używanie innych technik pozwalających na uzyskiwanie w zautomatyzowany sposób dostępu do zasobów serwisów w celu ich dalszego wykorzystania, z celowym pominięciem usługi Allegro WebAPI.
  3. Zalecane jest regularne odwiedzanie bloku Aktualności na stronie WebAPI. Zapowiadane są tam z wyprzedzeniem wszelkie zmiany mające mieć miejsce w usłudze, znaleźć tam też można komunikaty techniczne mające wpływ na usługę (np. informacje o przerwach technicznych). Dzięki informacjom zawartym na stronie Aktualności, programista ma każdorazowo czas na dostosowanie swojej aplikacji do planowanych wdrożeń. Alternatywą dla regularnych odwiedzin Aktualności jest subskrypcja dostępnego na stronie kanału RSS, co pozwoli programiście być zawsze "na bieżąco" ze zmianami w WebAPI i uniknąć sytuacji, w której dany obszar w aplikacji przestaje działać z powodu przeoczenia zapowiadanych modyfikacji.
  4. W przypadku napotkania problemów podczas pisania kodu aplikacji warto zwrócić się po pomoc na forum Allegro WebAPI. Nasze forum jest regularnie śledzone zarówno przez pracowników Allegro odpowiedzialnych za WebAPI, jak i przez doświadczonych autorów oprogramowania opartego na WebAPI, którzy zawsze służą pomocą i dobrą radą.
  5. Kiedy aplikacja będzie już gotowa, zachęcamy do zamieszczenia informacji o niej w Katalogu aplikacji - powinno to znacznie pomóc w popularyzacji rozwiązania.

Hasła, bezpieczeństwo, wrażliwe dane

  1. Rozpowszechnianie oprogramowania, które do działania wymaga podania loginu i hasła użytkownika nie będącego twórcą tego oprogramowania, wymaga uprzedniej zgody Allegro (o czym mówi punkt V.3. Regulaminu WebAPI). W celu uzyskania takiej zgody, należy kontaktować się z serwisem poprzez formularz kontaktowy.
  2. Hasła do konta oraz dane osobowe użytkowników serwisu Allegro nie powinny być zapisywane na serwerze aplikacji lub w samej aplikacji.
  3. Jeżeli specyfika aplikacji wymaga zapisywania wrażliwych danych na serwerze lub w bazie lokalnej, wymagane jest wówczas przechowywanie ich w formie zaszyfrowanej i poinformowanie o tym fakcie użytkowników aplikacji. Odpowiedzialność za bezpieczeństwo zapisywanych danych leży po stronie aplikacji oraz jej autora.
  4. Formularz logowania prezentowany w aplikacji powinien zawierać:
    • maskowanie hasła do konta użytkownika,
    • informację, że login i hasło są wykorzystywane wyłącznie do komunikacji z Allegro i nigdy nie będą wykorzystywane w innym celu.
  5. Użytkownik aplikacji powinien mieć możliwość usunięcia w dowolnym momencie swojego konta na serwerze lub w bazie lokalnej, wraz ze wszystkimi danymi o nim oraz jego kontrahentach.

Klucze, dostęp

  1. Aplikacja działać powinna na jednym konkretnym kluczu WebAPI.
  2. Klucz wykorzystywany przez aplikację powinien być zaszyty w kodzie oprogramowania i działać powinien w sposób transparentny dla użytkownika aplikacji.
  3. Wartość klucza przypisanego do aplikacji nie powinna być widoczna dla użytkownika aplikacji, nie powinna być także udostępniana osobom niepowołanym.
  4. Nie należy wymuszać na użytkownikach aplikacji generowania własnych kluczy WebAPI, aby mogli oni skorzystać z oprogramowania.

Techniczne, optymalizacja, dobre wzorce

  1. Aby zapewnić pełną kompatybilność z serwisem Allegro, zalecane jest używanie w aplikacji kodowania znaków UTF-8.
  2. Komunikaty błędów powinny być obsłużone w sposób przyjazny dla użytkowników aplikacji. Zamiast kodu błędu aplikacja powinna prezentować komunikat o błędzie zawarty w polu fault-string.
  3. Zalecana jest maksymalna optymalizacja aplikacji pod względem liczby wywołań poszczególnych metod, wykorzystywanych zasobów oraz rozłożenia ruchu w czasie. W szczególności:
    • należy dbać, by optymalnie zarządzać sesjami i nie przekraczać limitu 10 jednocześnie ustanowionych sesji zalogowania,
    • należy upewnić się, iż wykorzystywane są tylko te metody, które faktycznie niezbędne są do pozyskania pożądanych danych,
    • warto pamiętać o tym, że obsługę reakcji na konkretne zdarzenia można znacznie zoptymalizować dzięki odpowiedniemu wykorzystaniu mechanizmów udostępnianych w ramach dzienników zdarzeń,
    • w przypadku, gdy serwer WebAPI zwraca kod błędu w odpowiedzi na jakąś akcję, zalecane jest ograniczenie kolejnych prób automatycznego podejmowania tej samej akcji do 4-5. Przekazywanie w takim przypadku do metody tych samych parametrów w niekończącej się pętli jest bezcelowe, może prowadzić do nałożenia blokady i powinno być obsłużone w kodzie odpowiednim wyjątkiem.
  4. Sygnalizacja zmian w drzewie kategorii i/lub polach formularza sprzedaży, powinna być odpowiednio obsłużona przez aplikację, a poszczególne komponenty powinny być odświeżane automatycznie, lub powinny zostać oznaczone jako możliwe do odświeżenia przez użytkownika aplikacji każdorazowo w momencie wykrycia zmiany klucza wersji w danym kraju.
  5. W przypadku aplikacji płatnych, warto rozważyć bezpłatne udostępnianie ich wersji demonstracyjnych. Dzięki takiemu rozwiązaniu, potencjalni przyszli klienci będą w stanie przetestować oprogramowanie (ograniczone czasowo lub funkcjonalnie), mogąc zapoznać się z jego możliwościami jeszcze przed podjęciem faktycznej decyzji o jego zakupie.


Ostatnia aktualizacja: 19.03.2012 r.