# HG changeset patch # User Michał Rudowicz # Date 1301906649 -7200 # Node ID 8dabb7e7f03949eb9f40b7a7f6a7a79d2c3f816d # Parent 57a48d2aee18c1d653adb8e789d931c90dd5a64e API zdefiniowane przez szablon diff -r 57a48d2aee18 -r 8dabb7e7f039 frontend/doc/api.txt --- a/frontend/doc/api.txt Sun Apr 03 14:07:19 2011 +0200 +++ b/frontend/doc/api.txt Mon Apr 04 10:44:09 2011 +0200 @@ -1,36 +1,72 @@ 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///``, gdzie: - -apikey - Klucz API taki, jak ustawiony w pliku config.ini -ID - Identyfikator zadania +``/api/getjob//``, 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 +``/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 ````, 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//`` 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///``, 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//``, gdzie: diff -r 57a48d2aee18 -r 8dabb7e7f039 frontend/mfrontend/templates/joblist.csv --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/frontend/mfrontend/templates/joblist.csv Mon Apr 04 10:44:09 2011 +0200 @@ -0,0 +1,3 @@ +{% for job in jobs %} +{{job.id}};{{job.hash}};{{job.method}};{# W razie czego dodać kolejne pola w ten sam sposób #} +{% endfor %} diff -r 57a48d2aee18 -r 8dabb7e7f039 frontend/mfrontend/views/api.py --- a/frontend/mfrontend/views/api.py Sun Apr 03 14:07:19 2011 +0200 +++ b/frontend/mfrontend/views/api.py Mon Apr 04 10:44:09 2011 +0200 @@ -2,20 +2,20 @@ # -*- coding: utf-8 -*- from flask import jsonify, Module, abort, request +from flask import render_template from mfrontend import db, utils, exceptions, decorators api = Module(__name__) -@api.route('/getjob//') -def get_jobs(): +@api.route('/getjob/') +@decorators.login_required +def get_jobs_json(): """ Funkcja pobiera informacje o wszystkich zadaniach i zwraca je w formacie JSON. """ - if apikey != db.config.get('Basic', 'ApiKey'): - abort(403) return jsonify(jobs = db.get_jobs(None, None, None)) @api.route('/getnextjob//') -def get_first_waiting_job(apikey): +def get_first_waiting_job_template(apikey): """ Zwraca w formacie JSON informacje o pierwszym czekającym zadaniu. @@ -24,21 +24,35 @@ """ if apikey != db.config.get('Basic', 'ApiKey'): abort(403) - return jsonify(job = db.get_waiting_job()) + return render_template('joblist.csv', + jobs = [ db.get_waiting_job() ] ) -@api.route('/getjob///') -def get_job(apikey, jobid): +@api.route('/getjob//') +@decorators.login_required +def get_job_json(jobid): """ Zwraca w formacie JSON informacje o podanym zadaniu. - :param jobid: Identyfikator żądanego zadania. - :param apikey: Klucz API + :param jobid: Identyfikator żądanego zadania. + :returns: Informacje o zadaniu w formacie JSON """ - # jeśli klucz API jest niepoprawny, przerywamy - if apikey != db.config.get('Basic','ApiKey'): - abort(403) # w innym przypadku zwracamy informacje o zadaniu return jsonify(job = db.get_job_by_id(jobid)) +@api.route('/getjob///') +def get_job_template(apikey, jobid): + """ Funkcja zwraca informacje o zadaniu o podanym numerze + jobid. + + :param apikey: Klucz API taki, jak ustawiony w config.ini + :param jobid: Numer identyfikacyjny zadania + :returns: Dane o zadaniu wyrenderowane przy pomocy + szablonu joblist.csv + """ + if apikey != db.config.get('Basic', 'ApiKey'): + abort(403) + return render_template('joblist.csv', + jobs = [ db.get_job_by_id(jobid) ] ) + @api.route('/modify///', methods=['POST']) def modify_job(apikey, jobid): """ Funkcja pozwalająca na modyfikację wybranego