started apidoc
This commit is contained in:
seba
parent
793162c060
commit
b2438f2981
|
|
@ -6,27 +6,22 @@ from django.contrib.auth.decorators import user_passes_test
|
|||
from django.contrib.auth.models import Group
|
||||
from decorators import *
|
||||
from decimal import Decimal, InvalidOperation
|
||||
from helper import *
|
||||
import datetime
|
||||
|
||||
def getInt(d, key, default):
|
||||
try:
|
||||
return int(d.get(key, default))
|
||||
except ValueError:
|
||||
return default
|
||||
|
||||
def getDecimal(d, key, default):
|
||||
try:
|
||||
return Decimal(d.get(key, default))
|
||||
except InvalidOperation:
|
||||
return default
|
||||
|
||||
class BuyableItemHandler(BaseHandler):
|
||||
"""Handler responsible for getting and buying items."""
|
||||
|
||||
allowed_methods = ('GET', 'POST')
|
||||
#fields = ('id', 'description')
|
||||
model = Buyable
|
||||
exclude = ('_*',)
|
||||
|
||||
def read(self, request, itemId=None):
|
||||
"""Get one or multiple items.
|
||||
|
||||
- type: Only get items belonging to this type
|
||||
"""
|
||||
if itemId == None:
|
||||
if request.GET.has_key('type'):
|
||||
obj = Buyable.objects.filter(buyableType__name=request.GET['type'])
|
||||
|
|
@ -42,6 +37,12 @@ class BuyableItemHandler(BaseHandler):
|
|||
|
||||
@manglePluginPerms
|
||||
def create(self, request, itemId=None):
|
||||
"""Buy a :class:`Buyable <buyable.models.Buyable>` item.
|
||||
|
||||
- deposit Set to > 0 if you want to buy the item with deposit (default 0)
|
||||
- amount amount of items to buy (default 1)
|
||||
"""
|
||||
|
||||
if not request.content_type:
|
||||
request.data = request.POST
|
||||
if not itemId:
|
||||
|
|
@ -75,15 +76,26 @@ class BuyableItemHandler(BaseHandler):
|
|||
return rc.CREATED
|
||||
|
||||
class BuyableTypeHandler(BaseHandler):
|
||||
"""Handler for listing all :class:`BuyableType <buyable.models.BuyableType>`.
|
||||
|
||||
This class only supports read requests which won't accept
|
||||
any arguments. It will give you a list of buyable-types.
|
||||
Nothing more, nothing less.
|
||||
"""
|
||||
allowed_methods = ('GET',)
|
||||
model = BuyableType
|
||||
|
||||
class HistoryHandler(BaseHandler):
|
||||
"""Handler providing access to the users history """
|
||||
allowed_methods = ('GET',)
|
||||
fields = ('id', 'price', 'dateTime', ('purchase_set', (('buyable', ('id', )), 'price', 'name')))
|
||||
|
||||
@manglePluginPerms
|
||||
def read(self, request):
|
||||
"""Get the users history
|
||||
|
||||
- num: Number of entries to return
|
||||
"""
|
||||
num = getInt(request.GET, 'num', 0)
|
||||
qset = Order.objects.filter(user=request.user)
|
||||
if num > 0:
|
||||
|
|
@ -92,12 +104,22 @@ class HistoryHandler(BaseHandler):
|
|||
|
||||
|
||||
class TransactionTransactHandler(BaseHandler):
|
||||
"""Handler for transaction.
|
||||
|
||||
This hanlder takes care of adding money to accounts and returning
|
||||
previous moneytransfers
|
||||
"""
|
||||
|
||||
allowed_methods = ('GET', 'POST')
|
||||
model = Transaction
|
||||
fields = ('amount', 'dateTime', 'checked', ('transactionType', ('id', 'name')))
|
||||
|
||||
@manglePluginPerms
|
||||
def read(self, request):
|
||||
"""Return the users last transactions
|
||||
|
||||
- num: Number of entries to return
|
||||
"""
|
||||
num = getInt(request.GET, 'num', 0)
|
||||
if num < 0:
|
||||
return rc.BAD_REQUEST
|
||||
|
|
@ -109,6 +131,11 @@ class TransactionTransactHandler(BaseHandler):
|
|||
|
||||
@manglePluginPerms
|
||||
def create(self, request):
|
||||
"""Transact money to an account
|
||||
|
||||
- amount: [req] Amount to add to the users account
|
||||
- type: [req]Type of transaction (id)
|
||||
"""
|
||||
amount = getDecimal(request.POST, 'amount', Decimal(0))
|
||||
tTypeId = getInt(request.POST, 'type', -1)
|
||||
|
||||
|
|
@ -133,23 +160,41 @@ class TransactionTransactHandler(BaseHandler):
|
|||
return rc.ALL_OK
|
||||
|
||||
class TransactionTypeHandler(BaseHandler):
|
||||
"""Handler for :class:`Transaction Types <transaction.models.TransactionType>`
|
||||
|
||||
Supplies a list of Transaction Types
|
||||
"""
|
||||
allowed_methods = ('GET',)
|
||||
model = TransactionType
|
||||
|
||||
class AccountBalanceHandler(BaseHandler):
|
||||
"""Handler for the users account balance"""
|
||||
allowed_methods = ('GET',)
|
||||
|
||||
@manglePluginPerms
|
||||
def read(self, request):
|
||||
"""Returns the users current account balance"""
|
||||
balance = request.user.get_profile().balance
|
||||
return {'balance': balance}
|
||||
|
||||
class AuthBlobHandler(BaseHandler):
|
||||
"""Handler to read and write an users authblob
|
||||
|
||||
Currently these functions are only available for a plugin user.
|
||||
Other users will get a rc.FORBIDDEN. Keep in mind that, to use
|
||||
these functions a plugin needs the permissions to do this in its
|
||||
configuration.
|
||||
"""
|
||||
allowed_methods = ('GET', 'POST')
|
||||
|
||||
@requirePlugin
|
||||
@manglePluginPerms
|
||||
def read(self, request):
|
||||
"""Read the users authblob
|
||||
|
||||
To use this function the plugin needs
|
||||
:attr:`main.models.Plugin.pluginCanReadAuthblob` to be true.
|
||||
"""
|
||||
if not request.plugin.pluginCanReadAuthblob:
|
||||
ret = rc.FORBIDDEN
|
||||
ret.write("\nThis plugin is not allowed to read the users authblob\n")
|
||||
|
|
@ -159,6 +204,16 @@ class AuthBlobHandler(BaseHandler):
|
|||
@requirePlugin
|
||||
@manglePluginPerms
|
||||
def create(self, request):
|
||||
"""Write the users authblob.
|
||||
|
||||
To use this function the plugin needs
|
||||
:attr:`main.models.Plugin.pluginCanWriteAuthblob` to be true.
|
||||
|
||||
.. Note:: In fact this method *should* be an update method, but for
|
||||
compability reasons (wget usage) it was decided to make
|
||||
this accessible as a create (POST) hook.
|
||||
|
||||
"""
|
||||
if not request.plugin.pluginCanWriteAuthblob:
|
||||
ret = rc.FORBIDDEN
|
||||
ret.write("\nThis plugin is not allowed to write the users authblob\n")
|
||||
|
|
@ -172,11 +227,22 @@ class AuthBlobHandler(BaseHandler):
|
|||
return rc.ALL_OK
|
||||
|
||||
class AuthUserHandler(BaseHandler):
|
||||
""" Handler for mapping an authblob to a user
|
||||
|
||||
This handler is only available to plugins and only if
|
||||
:attr:`unique authblob <main.models.Plugin.uniqueAuthblob>`
|
||||
is set for this plugin. Then it will provide a mapping from
|
||||
an authblob to a specifig user.
|
||||
"""
|
||||
allowed_methods = ('GET')
|
||||
fields = ('id', 'username')
|
||||
|
||||
@requirePlugin
|
||||
def read(self, request):
|
||||
"""Returns an user if one can be found, else rc.GONE
|
||||
|
||||
- authblob: [required] Authblob to search
|
||||
"""
|
||||
if not request.plugin.uniqueAuthblob:
|
||||
ret = rc.BAD_REQUEST
|
||||
ret.write("\nThis plugin does not support unique auth blobs, therefore we can't identify an user uniquely by its authblob\n")
|
||||
|
|
@ -192,10 +258,19 @@ class AuthUserHandler(BaseHandler):
|
|||
return rc.NOT_FOUND
|
||||
|
||||
class ConfigHandler(BaseHandler):
|
||||
""" Handler for API configuration values
|
||||
|
||||
This handler provides some API related configuration values"""
|
||||
allowed_methods = ('GET',)
|
||||
|
||||
def read(self, request):
|
||||
"""Get API configuration values
|
||||
|
||||
Currently returns the API version and mediaurl (where to
|
||||
find images etc.)
|
||||
"""
|
||||
return {
|
||||
'version': '0.1',
|
||||
'mediaurl': 'http://devcat.someserver.de:13805/media',
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,13 @@
|
|||
from decimal import Decimal, InvalidOperation
|
||||
|
||||
def getInt(d, key, default):
|
||||
try:
|
||||
return int(d.get(key, default))
|
||||
except ValueError:
|
||||
return default
|
||||
|
||||
def getDecimal(d, key, default):
|
||||
try:
|
||||
return Decimal(d.get(key, default))
|
||||
except InvalidOperation:
|
||||
return default
|
||||
|
|
@ -0,0 +1 @@
|
|||
_build/*
|
||||
|
|
@ -16,7 +16,13 @@ import sys, os
|
|||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#sys.path.append(os.path.abspath('.'))
|
||||
sys.path.append(os.path.abspath('..'))
|
||||
sys.path.append(os.path.abspath('../..'))
|
||||
|
||||
# django specific configuration
|
||||
from django.conf import settings
|
||||
settings.configure()
|
||||
|
||||
|
||||
# -- General configuration -----------------------------------------------------
|
||||
|
||||
|
|
@ -38,7 +44,7 @@ master_doc = 'index'
|
|||
|
||||
# General information about the project.
|
||||
project = u'k4ever'
|
||||
copyright = u'2011, TrollWare, FarbDev, others'
|
||||
copyright = u'2011, TrollWare, FarbDev and others'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
|
|
@ -173,7 +179,7 @@ htmlhelp_basename = 'k4everdoc'
|
|||
# (source start file, target name, title, author, documentclass [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'k4ever.tex', u'k4ever Documentation',
|
||||
u'TrollWare, FarbDev, others', 'manual'),
|
||||
u'TrollWare, FarbDev and others', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
|
|
@ -196,3 +202,4 @@ latex_documents = [
|
|||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
intersphinx_mapping = {'http://docs.python.org/': None}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,134 @@
|
|||
API
|
||||
===
|
||||
- explain a bit how piston/REST works
|
||||
- how to access the read/write/put/create functions
|
||||
- what this api does and what not
|
||||
|
||||
Authentication
|
||||
--------------
|
||||
- how does authentication work
|
||||
- what is the plugin authentication
|
||||
- when does a plugin need an user?
|
||||
- how to change user names
|
||||
|
||||
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
|
||||
========= =======================
|
||||
|
||||
: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
|
||||
: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:
|
||||
|
||||
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
|
||||
^^^^^^^^^^^
|
||||
|
||||
|
|
@ -10,6 +10,8 @@ Contents:
|
|||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
django/api
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
|
|||
Loading…
Reference in New Issue