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