API HTTP | Dokumentacja API

Jak już wspomnieliśmy we wprowadzeniu, komunikacja z serwerem eLibri odbywa się poprzez protokół http. Żeby ułatwić zrozumienie dokumentacji, załączamy przykłady wywołania programu curl Żeby przykłady były czytelne, zakładamy, że login i hasło dostępowe zostały wyeksportowane do zmiennych shell-a (podany login i hasło oczywiście nie działają, prosimy o kontakt, żeby otrzymać konto testowe):

export ELIBRI_API_LOGIN=7792cdaced1a488dba6d
export ELIBRI_API_PASSWORD=7792cdaced1a488dba6d

+POST/api/v1/queues/:queue_name/pop

Pobiera dane z kolejki

Pobiera dane z kolejki :queue_name, gdzie :queue_name może przyjmować wartości 'meta' lub 'stocks'. W treści żądania można przekazać trzy argumenty: count , testing oraz offset (tylko gdy testing=1) . Parametr count jest opcjonalny i oznacza maksymalną ilość produktów, które jednorazowo zdejmujemy z kolejki. API akceptuje wartość count pomiędzy 1 i 100.
Wymagane jest natomiast podanie nagłówka HTTP X-eLibri-API-ONIX-dialect . Obecnie może on przyjmować wartość: 3.0.1

Gdy parametr testing ma wartość 1, dane nie są w rzeczywistości usuwane z kolejki oczekującej. Taki request można wykonywać wielokrotnie i za każdym razem zwraca te same dane (dane produktów z początku kolejki oczekującej).

Aby uprościć parsowanie odpowiedzi (brak konieczności dodatkowych przestrzeni nazw w XML`u), metadane POP`u zostały przeniesione do nagłówków HTTP. Wykorzystywane są do tego celu nagłówki X-eLibri-API-pop-* Gdy X-eLibri-API-pop-products-count równe jest 0, odpowiedź od serwera nie zawiera żadnych danych. Oznacza to iż pobraliśmy już wszystkie dane z kolejki. Parametr offset może być używany tylko w połączeniu z parametrem testing=1, i pozwala na przeglądanie całej kolejki, bez jej modyfikowania. Domyślnie parametr ten przyjmuje wartość 0, czyli zwracane są dane z początku kolejki.

Gdy są oczekujące dane

200

X-eLibri-API-pop-created-at:: 2011-10-04 12:02:07 UTC
X-eLibri-API-pop-products-count:: 20
X-eLibri-API-pop-queue-name:: meta

<ONIXMessage xmlns:elibri="http://elibri.com.pl/ns/extensions" xmlns="http://www.editeur.org/onix/3.0/reference" release="3.0">
  <elibri:Dialect>3.0.1</elibri:Dialect>
  <Header>
    <Sender>
      <SenderName>Elibri.com.pl</SenderName>
      <ContactName>Tomasz Meka</ContactName>
      <EmailAddress>kontakt@elibri.com.pl</EmailAddress>
    </Sender>
    <SentDateTime>20110906</SentDateTime>
  </Header>

  <Product>
    <!-- [...] -->
  </Product>
  <Product>
    <!-- [...] -->
  </Product>
</ONIXMessage>

Gdy nie ma danych oczekujących

200

X-eLibri-API-pop-products-count:: 0

Gdy kolejka nie istnieje

404

<error id='1001'>
  <message>Queue does not exist</message>
</error>

curl -i -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     -H "X-eLibri-API-ONIX-dialect: 3.0.1" \
     -d "count=1&testing=1" -X POST \
     https://www.elibri.com.pl/api/v1/queues/meta/pop

+POST/api/v1/queues/refill_all

Wypełnij kolejki

Użyteczne w przypadku konieczności pełnej synchronizacji z eLibri. Kolejki są wypełniane danymi o wszystkich produktach.

Gdy wszystko ok

200

Location:: http://elibri.com.pl/api/v1/queues

curl -i -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     -X POST \
     https://www.elibri.com.pl/api/v1/queues/refill_all

+POST/api/v1/queues/:queue_name/remove/:record_reference

Modyfikacja kolejki

Z kolejki jest usuwany produkt o określonym record_refence. Zwracany jest kod 200, jeśli wszystko jest ok, lub błąd, gdy podana zostanie błędna nazwa kolejki, lub gdy nie istnieje produkt o określonym record_reference. Ta operacja jest rzadko potrzebna, może być przydatna, gdy proces akceptacji danych po stronie klienta jest interaktywnym procesem.

+GET/api/v1/queues

Sprawdzanie stanu kolejek danych.

Sprawdź, czy są jakieś oczekujące dane produktów do pobrania.

Gdy są oczekujące dane

200

<queues>
  <queue name="meta" products_count="24" last_insert_at="2011-02-05 21:02:22 UTC"/>
  <queue name="stocks" products_count="1500" last_insert_at="2011-02-05 21:02:22 UTC"/>
</queues>

Gdy nie ma danych oczekujących

200

<queues>
  <queue name="meta" products_count="0" />
  <queue name="stocks" products_count="0" />
</queues>

curl -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     https://www.elibri.com.pl/api/v1/queues

+GET/api/v1/queues/:queue_name/last_pop

Zwróć jeszcze raz dane ostatniego POP

W przypadku problemu z siecią, ten entrypoint pozwala na ponowne pobranie danych z ostatniego POP`a wykonanego na określonej kolejce.

Gdy są ostatnio pobrane dane

200

X-eLibri-API-pop-created-at:: 2011-10-04 12:02:07 UTC
X-eLibri-API-pop-products-count:: 20
X-eLibri-API-pop-queue-name:: meta

<?xml version="1.0" encoding="UTF-8"?>
<ONIXMessage xmlns:elibri="http://elibri.com.pl/ns/extensions" xmlns="http://www.editeur.org/onix/3.0/reference" release="3.0">
  <elibri:Dialect>3.0.1</elibri:Dialect>
  <Header>
    <Sender>
      <SenderName>Elibri.com.pl</SenderName>
      <ContactName>Tomasz Meka</ContactName>
      <EmailAddress>kontakt@elibri.com.pl</EmailAddress>
    </Sender>
    <SentDateTime>20110906</SentDateTime>
  </Header>

  <Product>
    <!-- [...] -->
  </Product>
  <Product>
    <!-- [...] -->
  </Product>
</ONIXMessage>

Gdy nie było wcześniej pobranych danych

412

<error id='1002'>
  <message>There is no recently popped data</message>
</error>

curl -i -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     -H "X-eLibri-API-ONIX-dialect: 3.0.1" \
     https://www.elibri.com.pl/api/v1/queues/meta/last_pop

+GET/api/v1/publishers

Lista dostępnych wydawnictw

Klienci, którzy mają ustawioną subskrypcję na jedno wydawnictwo, widzą tylko jedną pozycję na liście. Reszta widzi wszystko.

Gdy wszystko ok

200

<publishers>
  <publisher name="The MIT Press" city="Cambridge" company_name="The MIT Press" zip_code="MA 02142-1493" id="1" street="Hayward Street 55" phone1="(617) 253-5646">
    <products url="http://api.test/api/v1/publishers/1/products" count="2"/>
  </publisher>
  <publisher name="O'Reilly Media" city="Warszawa" www="http://www.abiekt.pl" company_name="Abiekt.pl Sp&#243;&#322;ka z o.o." zip_code="00-785" id="2" street="Grottgera 9a/7" phone1="609-626-500" nip="521-348-37-69" email="wojciech.szot@abiekt.pl">
    <products url="http://api.test/api/v1/publishers/2/products" count="3"/>
  </publisher>
</publishers>

curl -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     https://www.elibri.com.pl/api/v1/publishers

+GET/api/v1/publishers/pdw

Lista wydawnictw dystrybuowanych do PDW

Lista wydawnictw dystrybuowanych przez PDW, w formacie jak w liście wszystkich wydawców

+GET/api/v1/publishers/olesiejuk

Lista wydawnictw dystrybuowanych przez F.K.Olesiejuk

Lista wydawnictw dystrybuowanych przez Firmę Księgarską Olesiejuk (dystrybucja e-booków), w formacie jak w liście wszystkich wydawców

+GET/api/v1/publishers/:publisher_id/products

Lista produktów w wydawnictwie

Każdy tag produktu posiada URL zawierający dane ONIX oraz RecordReference z bazy ONIX.

Gdy wszystko ok

200

<publisher id="1020" name="Wydawnicta Naukowo-Techniczne">
  <products count="1200" url="http://api.elibri.com.pl/api/v1/publishers/1020/products">
    <product main_title="Erlang Programming" record_reference="04325b31fdece145d22e" url="http://api.elibri.com.pl/api/v1/products/04325b31fdece145d22e"/>
    <product main_title="The Little Schemer" record_reference="993140a24d8202a347cc" url="http://api.elibri.com.pl/api/v1/products/993140a24d8202a347cc"/>
    <product main_title="The Rails Way" record_reference="a40f41cf67facf1876e3" url="http://api.elibri.com.pl/api/v1/products/a40f41cf67facf1876e3"/>
    <!-- ... -->
  </products>
</publisher>

Gdy dane wydawnictwa są niedostępne

403

<error id='403'>
  <message>Forbidden</message>
</error>

curl -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     https://www.elibri.com.pl/api/v1/publishers/5/products

+GET/api/v1/products/:record_reference

ONIX wybranego produktu

Wymagane jest podanie nagłówka HTTP X-eLibri-API-ONIX-dialect . Obecnie może on przyjmować wartość: 3.0.1

Gdy wszystko OK

200

<?xml version="1.0" encoding="UTF-8"?>
<ONIXMessage release="3.0" xmlns:elibri="http://elibri.com.pl/ns/extensions" xmlns="http://www.editeur.org/onix/3.0/reference">
  <elibri:Dialect>3.0.1</elibri:Dialect>
  <Header>
    <Sender>
      <SenderName>Elibri.com.pl</SenderName>
      <ContactName>Tomasz Meka</ContactName>
      <EmailAddress>kontakt@elibri.com.pl</EmailAddress>
    </Sender>
    <SentDateTime>20111007</SentDateTime>
  </Header>

  <Product>
  </Product>

</ONIXMessage>

Gdy produkt nie istnieje

404

<error id='404'>
  <message>Not found</message>
</error>

Produkt niedostępny

403

<error id='403'>
  <message>Forbidden</message>
</error>

curl -k --digest -u $ELIBRI_API_LOGIN:$ELIBRI_API_PASSWORD \
     -H "X-eLibri-API-ONIX-dialect: 3.0.1" \
     https://www.elibri.com.pl/api/v1/products/91adec74ce091edadaab

Elibri

Dystrybucja informacji o książkach

API systemu Elibri

ONIX

Podglądy

Wydrukuj dokumentację

kontakt