diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_extensions/odoo_ext/static/layout.less | 4 | ||||
| -rw-r--r-- | doc/_extensions/odoo_ext/static/style.css | 24 | ||||
| -rw-r--r-- | doc/_extensions/odoo_ext/translator.py | 5 | ||||
| -rw-r--r-- | doc/index.rst | 2 | ||||
| -rw-r--r-- | doc/reference.rst | 1 | ||||
| -rw-r--r-- | doc/webservices.rst | 13 | ||||
| -rw-r--r-- | doc/webservices/flow.png | bin | 0 -> 14726 bytes | |||
| -rw-r--r-- | doc/webservices/iap.rst | 235 | ||||
| -rw-r--r-- | doc/webservices/odoo.rst (renamed from doc/api_integration.rst) | 6 | ||||
| -rw-r--r-- | doc/webservices/upgrade.rst (renamed from doc/reference/upgrade_api.rst) | 6 |
10 files changed, 274 insertions, 22 deletions
diff --git a/doc/_extensions/odoo_ext/static/layout.less b/doc/_extensions/odoo_ext/static/layout.less index c350defa2a1..4c8a5c64386 100644 --- a/doc/_extensions/odoo_ext/static/layout.less +++ b/doc/_extensions/odoo_ext/static/layout.less @@ -103,7 +103,7 @@ main.has_code_col{ > *{ max-width: 100%; } - section { + > section { position: relative; display:block; float: left; @@ -116,7 +116,7 @@ main.has_code_col{ &:before { .code-col(); } - section { + > section { > * { width: 54.633333%; max-width: 600px; diff --git a/doc/_extensions/odoo_ext/static/style.css b/doc/_extensions/odoo_ext/static/style.css index ead78f9101d..1442d4bdd67 100644 --- a/doc/_extensions/odoo_ext/static/style.css +++ b/doc/_extensions/odoo_ext/static/style.css @@ -9708,7 +9708,7 @@ main.has_code_col article.doc-body { main.has_code_col article.doc-body > * { max-width: 100%; } -main.has_code_col article.doc-body section { +main.has_code_col article.doc-body > section { position: relative; display: block; float: left; @@ -9730,36 +9730,36 @@ main.has_code_col article.doc-body section { top: 0; right: 0; } - main.has_code_col article.doc-body section > * { + main.has_code_col article.doc-body > section > * { width: 54.633333%; max-width: 600px; float: left; clear: left; } - main.has_code_col article.doc-body section > h1, - main.has_code_col article.doc-body section > h2, - main.has_code_col article.doc-body section > h3, - main.has_code_col article.doc-body section > h4, - main.has_code_col article.doc-body section > h5, - main.has_code_col article.doc-body section > h6 { + main.has_code_col article.doc-body > section > h1, + main.has_code_col article.doc-body > section > h2, + main.has_code_col article.doc-body > section > h3, + main.has_code_col article.doc-body > section > h4, + main.has_code_col article.doc-body > section > h5, + main.has_code_col article.doc-body > section > h6 { width: 100%; float: none; clear: none; } - main.has_code_col article.doc-body section .doc-aside { + main.has_code_col article.doc-body > section .doc-aside { width: 41%; float: none; clear: none; margin-right: 15px; margin-left: 57%; } - main.has_code_col article.doc-body section .doc-aside .content-switcher { + main.has_code_col article.doc-body > section .doc-aside .content-switcher { margin-top: 0; } - main.has_code_col article.doc-body section .doc-aside .content-switcher > ul { + main.has_code_col article.doc-body > section .doc-aside .content-switcher > ul { margin-bottom: 0; } - main.has_code_col article.doc-body section .doc-aside .content-switcher > ul > li { + main.has_code_col article.doc-body > section .doc-aside .content-switcher > ul > li { color: #dcddde; } } diff --git a/doc/_extensions/odoo_ext/translator.py b/doc/_extensions/odoo_ext/translator.py index 443458f33c7..c2349bca315 100644 --- a/doc/_extensions/odoo_ext/translator.py +++ b/doc/_extensions/odoo_ext/translator.py @@ -142,6 +142,11 @@ class BootstrapTranslator(nodes.NodeVisitor, object): if not self.section_level: self.body.append(u'</section>') + def visit_topic(self, node): + self.body.append(self.starttag(node, 'nav')) + def depart_topic(self, node): + self.body.append(u'</nav>') + def is_compact_paragraph(self, node): parent = node.parent if isinstance(parent, (nodes.document, nodes.compound, diff --git a/doc/index.rst b/doc/index.rst index 21231b7ce3f..8035da789f9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -14,7 +14,7 @@ Index :maxdepth: 2 tutorials - api_integration + webservices setup reference diff --git a/doc/reference.rst b/doc/reference.rst index d83ef3bb476..1b41f4cdbd2 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -21,5 +21,4 @@ Reference reference/reports reference/mixins reference/guidelines - reference/upgrade_api reference/mobile diff --git a/doc/webservices.rst b/doc/webservices.rst new file mode 100644 index 00000000000..3dad86448ba --- /dev/null +++ b/doc/webservices.rst @@ -0,0 +1,13 @@ +:banner: banners/web_service_api.jpg +:types: api + +============ +Web Services +============ + +.. toctree:: + :titlesonly: + + webservices/odoo + webservices/iap + webservices/upgrade diff --git a/doc/webservices/flow.png b/doc/webservices/flow.png Binary files differnew file mode 100644 index 00000000000..df4bf7cfbbb --- /dev/null +++ b/doc/webservices/flow.png diff --git a/doc/webservices/iap.rst b/doc/webservices/iap.rst new file mode 100644 index 00000000000..18af76900fb --- /dev/null +++ b/doc/webservices/iap.rst @@ -0,0 +1,235 @@ +:types: api + + +:code-column: + +.. _webservices/iap: + +================ +In-App Purchases +================ + +IAP allow providers of ongoing services through Odoo apps to be compensated +for ongoing service use rather than — and possibly instead of — a sole initial +purchase. + +In that context, Odoo acts mostly as a *broker* between the service user +(client) and the service provider (Odoo App developer): + +* users purchase service tokens from Odoo +* service providers draw tokens from the user's Odoo account + +.. attention:: + + This document is intended for *service providers* and presents the latter, + which can be done either via direct JSON-RPC2_ or if you are using Odoo + using the convenience helpers it provides. + +.. image:: flow.png + :align: center + +.. contents:: + :local: + +JSON-RPC2_ Transaction API +========================== + +* The IAP transaction API does not require using Odoo when implementing your + server gateway, calls are standard JSON-RPC2_. +* Calls use different *endpoints* but the same *method* on all endpoints + (``call``). +* Exceptions are returned as JSON-RPC2_ errors, the formal exception name is + available on ``data.name`` for programmatic manipulation. + +.. class:: ServiceKey + + Identifier generated for the provider's service. Each key (and service) + matches a token of a fixed value, as generated by the service provide. + + Multiple types of tokens correspond to multiple services e.g. SMS and MMS + could either be the same service (with an MMS being "worth" multiple SMS) + or could be separate services at separate price points. + + .. danger:: your service key *is a secret*, leaking your service key + allows other application developers to draw credits bought for + your service(s) + +.. class:: UserToken + + Identifier for a user account. + +.. class:: TransactionToken + + Transaction identifier, returned by the authorization process and consumed + by either capturing or cancelling the transaction + +.. exception:: odoo.addons.iap.models.iap.NoCreditError + + Raised during transaction authorization if the credits requested are not + currently available on the account (either not enough credits or too many + pending transactions/existing holds). + +.. exception:: odoo.addons.iap.models.iap.BadAuthError + + Raised by any operation to which a service token is required, if the + service token is invalid. + +Authorize +--------- + +.. function:: /iap/1/authorize + + Verifies that the user's account has at least as ``credit`` available + *and creates a hold (pending transaction) on that amount*. + + Any amount currently on hold by a pending transaction is considered + unavailable to further authorize calls. + + Returns a :class:`TransactionToken` identifying the pending transaction + which can be used to capture (confirm) or cancel said transaction. + + :param ServiceKey key: + :param UserToken account_token: + :param int credit: + :param str description: optional, helps users identify the reason for + charges on their accounts. + :returns: :class:`TransactionToken` if the authorization succeeded. + :raises: :class:`~odoo.addons.iap.models.iap.BadAuthError` if the service token is invalid + :raises: :class:`~odoo.addons.iap.models.iap.NoCreditError` if the account does + :raises: ``TypeError`` if the ``credit`` value is not an integer + +.. rst-class:: doc-aside + +.. code-block:: python + + r = requests.post(ODOO + '/iap/1/authorize', json={ + 'jsonrpc': '2.0', + 'id': None, + 'method': 'call', + 'params': { + 'account_token': user_account, + 'key': SERVICE_KEY, + 'credit': 25, + 'description': "Why this is being charged", + } + }).json() + if 'error' in r: + # handle authorize error + tx = r['result'] + + # provide your service here + +Capture +------- + +.. function:: /iap/1/capture + + Confirms the specified transaction, transferring the reserved credits from + the user's account to the service provider's. + + Capture calls are idempotent: performing capture calls on an already + captured transaction has no further effect. + + :param TransactionToken token: + :param ServiceKey key: + :raises: :class:`~odoo.addons.iap.models.iap.BadAuthError` + +.. rst-class:: doc-aside + +.. code-block:: python + + r2 = requests.post(ODOO + '/iap/1/capture', json={ + 'jsonrpc': '2.0', + 'id': None, + 'method': 'call', + 'params': { + 'token': tx, + 'key': SERVICE_KEY, + } + }).json() + if 'error' in r: + # handle capture error + # otherwise transaction is captured + +Cancel +------ + +.. function:: /iap/1/cancel + + Cancels the specified transaction, releasing the hold on the user's + credits. + + Cancel calls are idempotent: performing capture calls on an already + cancelled transaction has no further effect. + + :param TransactionToken token: + :param ServiceKey key: + :raises: :class:`~odoo.addons.iap.models.iap.BadAuthError` + +.. rst-class:: doc-aside + +.. code-block:: python + + r2 = requests.post(ODOO + '/iap/1/cancel', json={ + 'jsonrpc': '2.0', + 'id': None, + 'method': 'call', + 'params': { + 'token': tx, + 'key': SERVICE_KEY, + } + }).json() + if 'error' in r: + # handle cancel error + # otherwise transaction is cancelled + +Odoo Helpers +============ + +For convenience, if you are implementing your service using Odoo the ``iap`` +module provides a few helpers to make IAP flow even simpler: + +Charging +-------- + +.. class:: odoo.addons.iap.models.iap.charge(env, key, account_token, credit[, description]) + + A *context manager* for authorizing and automatically capturing or + cancelling transactions for use in the backend/proxy. + + Works much like e.g. a cursor context manager: + + * immediately authorizes a transaction with the specified parameters + * executes the ``with`` body + * if the body executes in full without error, captures the transaction + * otherwise cancels it + + :param odoo.api.Environment env: used to retrieve the ``iap.endpoint`` + configuration key + :param ServiceKey key: + :param UserToken token: + :param int credit: + :param str description: + +.. rst-class:: doc-aside + +.. code-block:: python + + @route('/deathstar/superlaser', type='json') + def superlaser(self, user_account, + coordinates, target, + factor=1.0): + """ + :param factor: superlaser power factor, + 0.0 is none, 1.0 is full power + """ + credits = int(MAXIMUM_POWER * factor) + with charge(request.env, SERVICE_KEY, user_account, credits): + # TODO: allow other targets + self.env['systems.planets'].search([ + ('grid', '=', 'M-10'), + ('name', '=', 'Alderaan'), + ]).unlink() + + +.. _JSON-RPC2: http://www.jsonrpc.org/specification diff --git a/doc/api_integration.rst b/doc/webservices/odoo.rst index 612e91ed854..f68862626a7 100644 --- a/doc/api_integration.rst +++ b/doc/webservices/odoo.rst @@ -4,9 +4,9 @@ :code-column: -=============== -Web Service API -=============== +=========================== +Odoo Remote Procedure Calls +=========================== Odoo is usually extended internally via modules, but many of its features and all of its data are also available from the outside for external analysis or diff --git a/doc/reference/upgrade_api.rst b/doc/webservices/upgrade.rst index 04edf919e83..fa168935b23 100644 --- a/doc/reference/upgrade_api.rst +++ b/doc/webservices/upgrade.rst @@ -6,9 +6,9 @@ .. _reference/upgrade-api: -=========== -Upgrade API -=========== +================ +Database Upgrade +================ Introduction ~~~~~~~~~~~~ |
