Przykłady

Zanim zalogujemy się do systemu Allegro, wymagane jest pobranie aktualnych kluczy wersji.
Poniższe przykłady wprowadzą Ciebie w meandry usługi.

Pobranie aktualnego klucza wersji:

curl -v http://api.allerest.pl/doQuerySysStatus?sysvar=1

Żądanie

> GET /doQuerySysStatus HTTP/1.1
> User-Agent: curl/7.40.0
> Host: api.allerest.pl
> Accept: */*

Odpowiedź

< HTTP/1.1 200 OK
< Date: Sun, 15 Mar 2015 10:42:39 GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: IdeaWebServer/v0.80
<
< {"info":"1.0","verKey":1426255180}

Oryginalna funkcja doQuerySysStatus posiada kilka wymaganych argumentów: sysvar, countryId, webapiKey.
webapiKey nigdy nie podajemy, gdyż alleREST nadpisuje tę wartość swoim kluczem.
countryId posiada przypasaną domyślną wartość 1 – Polska.

Logowanie do systemu

Wykorzystujemy wcześniej zwrócony klucz wersji verKey.

curl -v --data "localVersion=1426255180&userLogin=twojLogin&userPassword=twojeHaslo" http://api.allerest.pl/doLogin

lub

curl -v -H "Content-Type: application/json" --data "{\"localVersion\":\"1426255180\",\"userLogin\":\"twojLogin\",\"userPassword\":\"twojeHaslo\"}" http://api.allerest.pl/doLogin

Żądanie

> POST /doLogin HTTP/1.1
> User-Agent: curl/7.40.0
> Host: api.allerest.pl
> Accept: */*
> Content-Length: 67
> Content-Type: application/x-www-form-urlencoded
>
> localVersion=1426255180&userLogin=twojLogin&userPassword=twojeHaslo

Odpowiedź

< HTTP/1.1 200 OK
< Date: Sun, 15 Mar 2015 10:51:28 GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: IdeaWebServer/v0.80
<
< {"sessionHandlePart":"c8aaa44ce23fb1d945ea43ad72ce1059b63b1ac10bcc68\/\/00_1","userId":1234567,"serverTime":1426416688}

Pobranie danych zalogowanego użytkownika

Wykorzystamy tutaj wcześniej zwrócony identyfikator sesji sessionHandlePart.

curl --header "X-Session-Handle: c8aaa44ce23fb1d945ea43ad72ce1059b63b1ac10bcc68//00_1" http://api.allrest.pl/doGetMyData -v

Do przesłania identyfikatora sesji użyliśmy nagłówka HTTP, ale możesz przesłać go jak każdą inną zmienną, np. metodą POST w formacie JSON (patrz przykład logowania).

W tym przypadku należy zachować oryginalną nazwę zmiennej stosowaną przez funkcję z Allegro API, sessionId lub sessionHandle (informacje w dokumentacji). W przypadku nagłówka X-Session-Handle nie musimy się martwic o te różnice w nazewnictwie.
Nie zaleca się wysyłania identyfikatora sesji w zapytaniu GET ze względów bezpieczeństwa.

Żądanie

> GET /doGetMyData HTTP/1.1
> User-Agent: curl/7.40.0
> Host: api.allerest.pl
> Accept: */*
> X-Session-Handle: c8aaa44ce23fb1d945ea43ad72ce1059b63b1ac10bcc68//00_1

Odpowiedź

< HTTP/1.1 200 OK
< Date: Sun, 15 Mar 2015 10:59:21 GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: IdeaWebServer/v0.80
<
< {"userData": *** prywatne dane zostały usunięte na potrzeby przykładu ***}

W podanych przykładach nie ustawialiśmy nagłówka Accept ponieważ w chwili pisania niniejszego artykułu jedynym dostępnym zwracanym formatem był application/json.
Powinniśmy go jednak ustawiać za każdym razem na wartość application/json ponieważ w zależności od używanego klienta zwracany format danych może się zmienić (json, xml, html).

Kody odpowiedzi

Jako, że API Allegro nie było pisane z myślą o REST, liczba kodów jest nieco ograniczona.
Otrzymując odpowiedź 200 OK możemy spodziewać się poprawnego wysłania żądania HTTP.

Wywołanie funkcji:

curl http://api.allerest.pl/doQuerySysStatus?sysvar=10

spowoduje zwrócenie kodu 400 i błędu w formacie JSON:

> GET /doQuerySysStatus?sysvar=10 HTTP/1.1
> User-Agent: curl/7.40.0
> Host: api.allerest.pl
> Accept: */*
>
< HTTP/1.1 400
< Date: Fri, 20 Mar 2015 19:30:02 GMT
< Content-Type: application/json; charset=utf-8
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: IdeaWebServer/v0.80
<
{"faultstring":"Proszę wybrać poprawną opcję zapytania.","faultcode":"ERR_UN
KNOWN_FEATURE","faultactor":"doQuerySysStatus - Unknown feature"}

ze wzgledu na parametr sysvar, dla którego maksymalna wartość na tę chwilę to 5.

200 OK
Żądanie zakończone sukcesem.

400 Bad Request
Żądanie nie spełnia wymagań dotyczących składni, wymaganych parametrów, zasób nie istnieje itp.

401 Unauthorized
Wymagane logowanie. Kody Allegro generujące odpowiedz: ERR_AUTHORIZATION_ERROR, ERR_NO_SESSION, ERR_SESSION_EXPIRED.

500 Internal server error
Wewnętrzny błąd serwera.

503 Server Unavailable
Serwer czasowo niedostępny, np. z powodu zbyt dużej ilości żądań.

Jeśli zwrócony wynik oglądasz w przeglądarce i chciałbyś uzyskać odpowiedź w bardziej czytelnej formie, możesz dodać parametr pretty np.:

curl http://api.allerest.pl/doQuerySysStatus?sysvar=1&pretty=1