Porady dla osób korzystających z API
====================================

Pobieranie informacji w formacie JSON
-------------------------------------

Pobieranie informacji o zadaniu o danym ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Przy domyślnej konfiguracji pobranie danych o zadaniu o podanym ID wymaga
wykonania polecenia GET na elemencie pod adresem
``/api/getjob/<ID>/``, gdzie ID jest identyfikatorem zadania

Serwer aplikacji powinien zwrócić dokument w formacie JSON zawierający
wszystkie dane znajdujące się w bazie, dotyczące tego zadania.

Pobieranie informacji o wszystkich zadaniach
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``/api/getjob/`` , gdzie *apikey* ma takie samo znaczenie jak
powyżej.

Pobieranie informacji w formacie zdefiniowanym przez szablon
------------------------------------------------------------

Klucz API
^^^^^^^^^

Klucz API, w URLach określany jako ``<apikey>``, jest kluczem pozwalającym na dostęp
do informacji udostępnianych przez API i nie powinien być udostepniany nikomu poza
osobami odpowiedzialnymi za aplikację rozproszoną korzystającą z serwera aplikacji.
Klucz znajduje się w :ref:`config-ini`.

Szablon pliku
^^^^^^^^^^^^^

Szablon pliku znajduje się w katalogu ``mfrontend/templates/joblist.csv`` i może być
dowolnie dostosowywany według potrzeb serwera aplikacji.

Domyślny szablon pliku:

.. code-block:: jinja

    {% for job in jobs %}
    {{job.id}};{{job.hash}};{{job.method}};
    {% endfor %}

W razie potrzeby należy dodać kolejne pola w analogiczny sposób.

Pobieranie jednego oczekującego zadania
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``/api/getnextjob/<apikey>/`` pobiera następne oczekujące działanie (wg numeru ID,
najpierw mniejsze wartości). *Ważne*: samo pobranie informacji **nie** zmienia
statusu zadania, trzeba to zrobić ręcznie za pomocą edycji zadania.

Pobieranie informacji o zadaniu o danym ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Przy domyślnej konfiguracji pobranie danych o zadaniu o podanym ID wymaga
wykonania polecenia GET na elemencie pod adresem
``/api/getjob/<apikey>/<jobid>/``, gdzie ID jest identyfikatorem zadania

Serwer aplikacji powinien zwrócić dokument w formacie zdefiniowanym przez szablon
zawierający wszystkie dane znajdujące się w bazie dotyczące tego zadania.


Modyfikowanie danych zadania
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Należy wykonać *POST* na URI ``/api/modify/<apikey/<jobid>/``, gdzie:

apikey
    Klucz API z pliku config.ini
ID
    Identyfikator zadania

Natomiast jako dane POST należy przesłać nowe wartości, które chcemy wpisać do
bazy, przykładowo następująca linia poleceń programu CURL:

.. code-block:: bash

    $ curl --data "state=10&percent=40" localhost:5000/api/modify/apikey/1/

spowoduje ustawienie wartości ``state`` na 10 i ``percent`` na 40 przy zadaniu
o identyfikatorze ``1``.

Funkcje wykorzystywane w API
----------------------------

.. automodule:: mfrontend.views.api
    :members: