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
===
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 <main.models.Plugin>`
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
<main.models.PluginPermission>` object will be created to keep track of this.
k4evers API also has a *plugin* concept. :class:`Plugins <main.models.Plugin>`
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 <main.models.PluginPermission>` object
will be created to keep track of this.
Each :class:`PluginPermission <main.models.PluginPermission>` object has an
: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
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 <authblob-authentication>`).
@ -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/ <api2.handlers.HistoryHandler>`
:func:`GET <api2.handlers.HistoryHandler.read>`
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/ <api2.handlers.TransactionTransactHandler>`
:func:`GET <api2.handlers.TransactionTransactHandler.read>`
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 <buyable.models.TransactionType>`
:class:`balance/ <api2.handlers.AccountBalanceHandler>`
:func:`GET <api2.handlers.AccountBalanceHandler.read>`
Get users account balance
Get user's account balance
**auth/**
:class:`blob/ <api2.handlers.AuthBlobHandler>`
:func:`GET <api2.handlers.AuthBlobHandler.read>`
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 <api2.handlers.AuthBlobHandler.create>`
Set authblob if allowed
Set authblob if allowed by plugin configuration
.. _authblob-authentication:
:class:`user/ <api2.handlers.AuthUserHandler>`
:func:`GET <api2.handlers.AuthUserHandler.read>`
get user by authblob string - this function works only when plugin
has the :attr:`unique authblob <main.models.Plugin.uniqueAuthblob>` 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
<main.models.Plugin.uniqueAuthblob>` flag
========= =================
Parameter Description
========= =================
authblob [required] authblob to sear
authblob [required] authblob to search
========= =================
:class:`config/ <api2.handlers.ConfigHandler>`
@ -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