k4ever/k4ever/docs/django/api.rst

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``.

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.

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.


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.

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 
`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>`).

To do something as another user the plugin can, if allowed by the user, add
the `user`-parameter with the **username** (not the id) to all its requests.
E.g. to get the account balance of the user *cat* this would look like
`user/account/?user=cat`.

URLs
----
For more information about a specific method you can click on the url/method to get
to the handler or the responsible method for more documentation or code.

**buyable/**
  :class:`item/[itemId]/ <api2.handlers.BuyableItemHandler>`
  	:func:`GET <api2.handlers.BuyableItemHandler.read>`
  		Get a specific item or a full/type item list.

		=========	=======================
		Parameter	Description
  		=========	=======================
  		type		item belonging to type-group
		barcode		item with this barcode
  		=========	=======================

   	:func:`POST <api2.handlers.BuyableItemHandler.create>`
   		Buy a :class:`Buyable <buyable.models.Buyable>` (requires an ItemId)

		=========	=======================================================
		Parameter	Description
		=========	=======================================================
   		deposit		Set to > 0 if you want to buy with deposit (default 0)
   		amount		amount of items to buy (default 1)
		=========	=======================================================

  :class:`types/ <api2.handlers.BuyableTypeHandler>`
   	:func:`GET <api2.handlers.BuyableTypeHandler.read>`
   		List all types which an item can belong to
   
  :class:`history/ <api2.handlers.HistoryHandler>`
   	:func:`GET <api2.handlers.HistoryHandler.read>`
   		List the users last orders

		=========	=================
		Parameter	Description
		=========	=================
   		num			Number of entries
		=========	=================

**account/**
  **transactions/** or **transfers/**
   	:class:`transact/ or transfer/ <api2.handlers.TransactionTransactHandler>`
   		:func:`GET <api2.handlers.TransactionTransactHandler.read>`
   			List the users last transactions

			=========	=================
			Parameter	Description
			=========	=================
   			num			Number of entries
			=========	=================

   		:func:`POST <api2.handlers.TransactionTransactHandler.create>`
   			Transact money to an account

			=========	=================
			Parameter	Description
			=========	=================
   			amount		[required] Amount to add to the users account
   			type		[required] Type of transaction (id)
			=========	=================

  :class:`types/ <api2.handlers.TransactionTypeHandler>`
	:func:`GET <api2.handlers.TransactionTypeHandler.read>`
		List all available :class:`Transaction Types <buyable.models.TransactionType>`
  :class:`balance/ <api2.handlers.AccountBalanceHandler>`
	:func:`GET <api2.handlers.AccountBalanceHandler.read>`
		Get users 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
		=========	=================

	:func:`POST <api2.handlers.AuthBlobHandler.create>`
   		Set authblob if allowed

 .. _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

		=========	=================
		Parameter	Description
		=========	=================
   		authblob	[required] authblob to sear
		=========	=================

:class:`config/ <api2.handlers.ConfigHandler>`
   :func:`GET <api2.handlers.ConfigHandler.read>`
   		Display API configuration variables
 

Handler
-------
.. automodule:: api2.handlers
	:members:

Plugin Models
-------------
.. autoclass:: main.models.Plugin
	:members:

.. autoclass:: main.models.PluginPermission
	:members:

Decorators
----------
.. automodule:: api2.decorators
	:members:

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.


WGET
""""
``wget`` comes in handy at this task. At some point it might be that ``wget`` cannot provide full access to the API cause it is unable to send ``PUT`` and ``DELETE`` requests. For debugging purposes the flags `-Sd` are recommended.

.. code-block:: bash

    # 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
	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
	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
	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
""""
As one might see, ``curl`` is quite nice for accessing the API. ``curl`` also supports the ``HTTP``, ``PUT`` and ``DELETE`` methods.

.. code-block:: bash

    # find item with barcode
	curl --basic http://frundy:foobar@server/api/buyable/item/?barcode=4029764001807
	# buy 10 times item with id 3
	curl --basic -X POST --data "amount=10" http://fruny:foobar@server/api/buyable/item/3/
	# as plugin get users account balance
	curl --basic http://testplugin:maunz@server/api/buyable/account/balance/?user=frundy
	# as plugin buy 10 times item with id 3
	curl --basic -X POST --data "amount=10" http://testplugin:maunz@server/api/buyable/item/3/?user=frundy