seba
/
k4ever
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fixed some typos and rewrote some of the doku.

This commit is contained in:
theresa 2011-10-10 22:15:14 +02:00
parent e72e5838f1
commit 828a31ec67
1 changed files with 44 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
k4ever/docs/django/api.rst
View File

@ -1,37 +1,40 @@
API API
=== ===
K4ever has a REST-like API. This means every URL represents an object which has K4ever has a REST-like API. This means every URL represents an object which has
four functions: ``read``, ``create``, ``update`` and ``delete``. These functions are mapped four functions: ``read``, ``create``, ``update`` and ``delete``. These functions
to the ``HTTP``-Methods ``GET``, ``POST``, ``PUT`` and ``DELETE``. Most of the functionality are mapped to the ``HTTP``-Methods ``GET``, ``POST``, ``PUT`` and ``DELETE``.
uses only ``GET`` and ``POST``, so everything is accessible via ``wget``. Most of the functionality uses only ``GET`` and ``POST``, so everything is
accessible via ``wget``.
The API enables you to list available items, buy them and transtact money to your The API enables you to list available items, buy them and transact money to
accout. To get an idea what functions are available and how they are used scroll down your accout. To get an idea what functions are available and how they are used
to the URLs section. Some URLs take arguments. For a ``GET``-request you can attach scroll down to the URLs section. Some URLs take arguments. For a ``GET``-request
them normaly, e.g. `/buyable/item/?barcode=4029764001807`. For a ``POST``, ``PUT`` or you can attach them normally, e.g. `/buyable/item/?barcode=4029764001807`.
``DELETE`` request the parameters have to be put in the ``HTTP``-requests body. They For a ``POST``, ``PUT`` or ``DELETE`` request the parameters have to be put in
can be provided url, JSON or YAML-encoded - dealers choice. the ``HTTP``-request's body. They can be provided url, JSON or YAML-encoded -
dealer's choice.
Authentication can be done either per HTTP Basic Auth or, for AJAX-Requests, per Authentication can be done either per HTTP Basic Auth or, for AJAX-Requests,
cookie (as in "logged in via the webinterface"). Note that most ``HTTP``-libraries per cookie (as in "logged in via the webinterface"). Note that most
like pythons urllib2 (or as a tool ``wget``) don't send authenticationdata except ``HTTP``-libraries like python's urllib2 (or as a tool ``wget``) don't send
when being challenged with a ``HTTP 401 - Authentication required``, meaning that authentication data except when being challenged with a
every API-call requires the library to make two requests. In general this behaviour ``HTTP 401 - Authentication required``, meaning that every API-call requires
can be turned off. the library to make two requests. In general this behaviour can be turned off.
Plugins Plugins
-------------- --------------
k4evers API also has a *plugin*-concept. :class:`Plugins <main.models.Plugin>` k4evers API also has a *plugin* concept. :class:`Plugins <main.models.Plugin>`
can be allowed by users to buy items on their behalf. To do this the user can be allowed by users to buy items on their behalf, e.g. after scanning the
has to allow the plugin via the webinterface. A :class:`PluginPermission user's unique barcode. To do this the user has to allow the plugin via the
<main.models.PluginPermission>` object will be created to keep track of this. webinterface. A :class:`PluginPermission <main.models.PluginPermission>` object
will be created to keep track of this.
Each :class:`PluginPermission <main.models.PluginPermission>` object has an Each :class:`PluginPermission <main.models.PluginPermission>` object has an
:attr:`authblob <main.models.PluginPermission.authblob>` in which the plugin :attr:`authblob <main.models.PluginPermission.authblob>` in which the plugin
can save or access arbitrary data on a per-user basis. The plugin has several can save or access arbitrary data on a per-user basis. The plugin has several
configuration options for the `authblob`. They control read/write access for configuration options for the `authblob`. They control read/write access for
plugin (via API) or user (via webinterface) to the `authblob` and if the plugin (via API) or user (via webinterface) to the `authblob` and whether the
`authblob` has to be unique. The latter one can be useful if the `authblob` `authblob` has to be unique. The latter one can be useful if the `authblob`
is needed to be primary key and identify exactly one user is needed to be primary key and identify exactly one user
(see also :ref:`apilink <authblob-authentication>`). (see also :ref:`apilink <authblob-authentication>`).
@ -64,7 +67,7 @@ to the handler or the responsible method for more documentation or code.
========= ======================================================= ========= =======================================================
Parameter Description Parameter Description
========= ======================================================= ========= =======================================================
deposit Set to > 0 if you want to buy with deposit (default 0) deposit Set to 0 for no deposit, 1 for item+deposit and 2 for deposit only (default 0)
amount amount of items to buy (default 1) amount amount of items to buy (default 1)
========= ======================================================= ========= =======================================================
@ -74,7 +77,7 @@ to the handler or the responsible method for more documentation or code.
:class:`history/ <api2.handlers.HistoryHandler>` :class:`history/ <api2.handlers.HistoryHandler>`
:func:`GET <api2.handlers.HistoryHandler.read>` :func:`GET <api2.handlers.HistoryHandler.read>`
List the users last orders List the user's last orders
========= ================= ========= =================
Parameter Description Parameter Description
@ -86,7 +89,7 @@ to the handler or the responsible method for more documentation or code.
**transactions/** or **transfers/** **transactions/** or **transfers/**
:class:`transact/ or transfer/ <api2.handlers.TransactionTransactHandler>` :class:`transact/ or transfer/ <api2.handlers.TransactionTransactHandler>`
:func:`GET <api2.handlers.TransactionTransactHandler.read>` :func:`GET <api2.handlers.TransactionTransactHandler.read>`
List the users last transactions List the user's last transactions
========= ================= ========= =================
Parameter Description Parameter Description
@ -100,7 +103,7 @@ to the handler or the responsible method for more documentation or code.
========= ================= ========= =================
Parameter Description Parameter Description
========= ================= ========= =================
amount [required] Amount to add to the users account amount [required] Amount to add to the user's account
type [required] Type of transaction (id) type [required] Type of transaction (id)
========= ================= ========= =================
@ -109,34 +112,29 @@ to the handler or the responsible method for more documentation or code.
List all available :class:`Transaction Types <buyable.models.TransactionType>` List all available :class:`Transaction Types <buyable.models.TransactionType>`
:class:`balance/ <api2.handlers.AccountBalanceHandler>` :class:`balance/ <api2.handlers.AccountBalanceHandler>`
:func:`GET <api2.handlers.AccountBalanceHandler.read>` :func:`GET <api2.handlers.AccountBalanceHandler.read>`
Get users account balance Get user's account balance
**auth/** **auth/**
:class:`blob/ <api2.handlers.AuthBlobHandler>` :class:`blob/ <api2.handlers.AuthBlobHandler>`
:func:`GET <api2.handlers.AuthBlobHandler.read>` :func:`GET <api2.handlers.AuthBlobHandler.read>`
Return authblob if allowed or auth if str given Only available for plugins. Username needs to be specified with ?user=`name`
(currentyl only allowed for Plugin users) Return authblob of a specific user if allowed by plugin configuration
(currently only allowed for Plugin users)
========= =================
Parameter Description
========= =================
blob blob to get user from / auth user with, returns User or NULL
========= =================
:func:`POST <api2.handlers.AuthBlobHandler.create>` :func:`POST <api2.handlers.AuthBlobHandler.create>`
Set authblob if allowed Set authblob if allowed by plugin configuration
.. _authblob-authentication: .. _authblob-authentication:
:class:`user/ <api2.handlers.AuthUserHandler>` :class:`user/ <api2.handlers.AuthUserHandler>`
:func:`GET <api2.handlers.AuthUserHandler.read>` :func:`GET <api2.handlers.AuthUserHandler.read>`
get user by authblob string - this function works only when plugin Get user who corresponds to a specific authblob string, e.g. to identify him -
has the :attr:`unique authblob <main.models.Plugin.uniqueAuthblob>` flag set this works only when the plugin has set the :attr:`unique authblob
<main.models.Plugin.uniqueAuthblob>` flag
========= ================= ========= =================
Parameter Description Parameter Description
========= ================= ========= =================
authblob [required] authblob to sear authblob [required] authblob to search
========= ================= ========= =================
:class:`config/ <api2.handlers.ConfigHandler>` :class:`config/ <api2.handlers.ConfigHandler>`
@ -164,8 +162,8 @@ Decorators
Examples Examples
-------- --------
Here are some code examples how to use the API with different clients or languages. Here are some code examples of how to use the API with different clients or languages.
In these examples we have for authentication *frundy*/*foobar* as a normal user and *testplugin*/*maunz* as a plugin. In these examples we use *frundy*/*foobar* as authentication for a normal user and *testplugin*/*maunz* as a plugin.
WGET WGET
@ -176,11 +174,11 @@ WGET
# find item with barcode # find item with barcode
wget -qS -O- --auth-no-challenge --http-user=frundy --http-password=foobar http://server/api/buyable/item/?barcode=4029764001807 wget -qS -O- --auth-no-challenge --http-user=frundy --http-password=foobar http://server/api/buyable/item/?barcode=4029764001807
# buy 10 times item with id 3 # buy the item with id 3 10 times
wget -qS -O- --auth-no-challenge --http-user=frundy --http-password=foobar http://server/api/buyable/item/3/ --post-data "amount=10" wget -qS -O- --auth-no-challenge --http-user=frundy --http-password=foobar http://server/api/buyable/item/3/ --post-data "amount=10"
# as plugin get users account balance # as plugin, get user's account balance
wget -qS -O- --auth-no-challenge --http-user=testplugin --http-password=maunz http://server/api/buyable/account/balance/?user=frundy wget -qS -O- --auth-no-challenge --http-user=testplugin --http-password=maunz http://server/api/buyable/account/balance/?user=frundy
# as plugin buy 10 times item with id 3 # as plugin, buy item with id 3 10 times
wget -qS -O- --auth-no-challenge --http-user=testplugin --http-password=maunz http://server/api/buyable/item/3/ --post-data "amount=10&user=frundy wget -qS -O- --auth-no-challenge --http-user=testplugin --http-password=maunz http://server/api/buyable/item/3/ --post-data "amount=10&user=frundy
CURL CURL
@ -191,10 +189,10 @@ As one might see, ``curl`` is quite nice for accessing the API. ``curl`` also su
# find item with barcode # find item with barcode
curl --basic http://frundy:foobar@server/api/buyable/item/?barcode=4029764001807 curl --basic http://frundy:foobar@server/api/buyable/item/?barcode=4029764001807
# buy 10 times item with id 3 # buy the item with id 3 10 times
curl --basic -X POST --data "amount=10" http://fruny:foobar@server/api/buyable/item/3/ curl --basic -X POST --data "amount=10" http://fruny:foobar@server/api/buyable/item/3/
# as plugin get users account balance # as plugin get user's account balance
curl --basic http://testplugin:maunz@server/api/buyable/account/balance/?user=frundy curl --basic http://testplugin:maunz@server/api/buyable/account/balance/?user=frundy
# as plugin buy 10 times item with id 3 # as plugin, buy item with id 3 10 times
curl --basic -X POST --data "amount=10" http://testplugin:maunz@server/api/buyable/item/3/?user=frundy curl --basic -X POST --data "amount=10" http://testplugin:maunz@server/api/buyable/item/3/?user=frundy