annotate frontend/doc/api.rst @ 28:d017e2ab3027

Poprawki z rana 23 maja, prezentacja django-flask
author Michał Rudowicz <michal.rudowicz@fl9.eu>
date Mon, 23 May 2011 12:49:48 +0200
parents 3a2876457625
children
rev   line source
24
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
1 Porady dla osób korzystających z API
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
2 ====================================
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
3
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
4 Pobieranie informacji w formacie JSON
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
5 -------------------------------------
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
6
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
7 Pobieranie informacji o zadaniu o danym ID
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
8 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
9
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
10 Przy domyślnej konfiguracji pobranie danych o zadaniu o podanym ID wymaga
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
11 wykonania polecenia GET na elemencie pod adresem
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
12 ``/api/getjob/<ID>/``, gdzie ID jest identyfikatorem zadania
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
13
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
14 Serwer aplikacji powinien zwrócić dokument w formacie JSON zawierający
28
d017e2ab3027 Poprawki z rana 23 maja, prezentacja django-flask
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents: 24
diff changeset
15 wszystkie dane znajdujące się w bazie dotyczące tego zadania.
24
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
16
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
17 Pobieranie informacji o wszystkich zadaniach
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
18 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
19
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
20 ``/api/getjob/`` , gdzie *apikey* ma takie samo znaczenie jak
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
21 powyżej.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
22
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
23 Pobieranie informacji w formacie zdefiniowanym przez szablon
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
24 ------------------------------------------------------------
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
25
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
26 Klucz API
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
27 ^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
28
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
29 Klucz API, w URLach określany jako ``<apikey>``, jest kluczem pozwalającym na dostęp
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
30 do informacji udostępnianych przez API i nie powinien być udostepniany nikomu poza
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
31 osobami odpowiedzialnymi za aplikację rozproszoną korzystającą z serwera aplikacji.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
32 Klucz znajduje się w :ref:`config-ini`.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
33
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
34 Szablon pliku
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
35 ^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
36
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
37 Szablon pliku znajduje się w katalogu ``mfrontend/templates/joblist.csv`` i może być
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
38 dowolnie dostosowywany według potrzeb serwera aplikacji.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
39
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
40 Domyślny szablon pliku:
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
41
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
42 .. code-block:: jinja
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
43
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
44 {% for job in jobs %}
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
45 {{job.id}};{{job.hash}};{{job.method}};
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
46 {% endfor %}
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
47
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
48 W razie potrzeby należy dodać kolejne pola w analogiczny sposób.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
49
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
50 Pobieranie jednego oczekującego zadania
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
52
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
53 ``/api/getnextjob/<apikey>/`` pobiera następne oczekujące działanie (wg numeru ID,
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
54 najpierw mniejsze wartości). *Ważne*: samo pobranie informacji **nie** zmienia
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
55 statusu zadania, trzeba to zrobić ręcznie za pomocą edycji zadania.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
56
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
57 Pobieranie informacji o zadaniu o danym ID
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
58 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
59
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
60 Przy domyślnej konfiguracji pobranie danych o zadaniu o podanym ID wymaga
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
61 wykonania polecenia GET na elemencie pod adresem
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
62 ``/api/getjob/<apikey>/<jobid>/``, gdzie ID jest identyfikatorem zadania
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
63
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
64 Serwer aplikacji powinien zwrócić dokument w formacie zdefiniowanym przez szablon
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
65 zawierający wszystkie dane znajdujące się w bazie dotyczące tego zadania.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
66
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
67
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
68 Modyfikowanie danych zadania
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
69 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
70
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
71 Należy wykonać *POST* na URI ``/api/modify/<apikey/<jobid>/``, gdzie:
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
72
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
73 apikey
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
74 Klucz API z pliku config.ini
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
75 ID
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
76 Identyfikator zadania
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
77
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
78 Natomiast jako dane POST należy przesłać nowe wartości, które chcemy wpisać do
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
79 bazy, przykładowo następująca linia poleceń programu CURL:
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
80
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
81 .. code-block:: bash
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
82
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
83 $ curl --data "state=10&percent=40" localhost:5000/api/modify/apikey/1/
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
84
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
85 spowoduje ustawienie wartości ``state`` na 10 i ``percent`` na 40 przy zadaniu
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
86 o identyfikatorze ``1``.
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
87
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
88 Funkcje wykorzystywane w API
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
89 ----------------------------
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
90
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
91 .. automodule:: mfrontend.views.api
3a2876457625 małe zmiany w dokumentacji
Michał Rudowicz <michal.rudowicz@fl9.eu>
parents:
diff changeset
92 :members: