|
|
|
@ -1,22 +1,24 @@
|
|
|
|
|
API
|
|
|
|
|
===
|
|
|
|
|
- explain a bit how piston/REST works
|
|
|
|
|
- how to access the read/write/put/create functions
|
|
|
|
|
- what this api does and what not
|
|
|
|
|
|
|
|
|
|
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. It also has a *plugin*-concept. Plugins can be allowed by other user
|
|
|
|
|
|
|
|
|
|
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. The
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
k4evers API
|
|
|
|
|
|
|
|
|
|
Plugins
|
|
|
|
|
--------------
|
|
|
|
@ -25,7 +27,24 @@ Plugins
|
|
|
|
|
- when does a plugin need an user?
|
|
|
|
|
- how to change user names
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
----
|
|
|
|
@ -111,6 +130,9 @@ to the handler or the responsible method for more documentation or code.
|
|
|
|
|
|
|
|
|
|
: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
|
|
|
|
@ -132,20 +154,21 @@ Handler
|
|
|
|
|
.. automodule:: api2.handlers
|
|
|
|
|
:members:
|
|
|
|
|
|
|
|
|
|
Plugin Models
|
|
|
|
|
-------------
|
|
|
|
|
.. autoclass:: main.models.Plugin
|
|
|
|
|
:members:
|
|
|
|
|
|
|
|
|
|
.. autoclass:: main.models.PluginPermission
|
|
|
|
|
:members:
|
|
|
|
|
|
|
|
|
|
Decorators
|
|
|
|
|
----------
|
|
|
|
|
.. automodule:: api2.decorators
|
|
|
|
|
:members:
|
|
|
|
|
|
|
|
|
|
Examples
|
|
|
|
|
--------
|
|
|
|
|
- how to use the api
|
|
|
|
|
- examples with... wget.. python-rest?
|
|
|
|
|
|
|
|
|
|
As normal user
|
|
|
|
|
^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. note:: there will be cat content
|
|
|
|
|
|
|
|
|
|
wget
|
|
|
|
|
""""
|
|
|
|
|
wget part
|
|
|
|
|
|
|
|
|
|
As a plugin
|
|
|
|
|
^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|