[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[GNUnet-SVN] [taler-api] 15/22: Fix missing links, commenting out superf
From: |
gnunet |
Subject: |
[GNUnet-SVN] [taler-api] 15/22: Fix missing links, commenting out superfluous/outdated section |
Date: |
Fri, 27 Jan 2017 10:52:35 +0100 |
This is an automated email from the git hooks/post-receive script.
marcello pushed a commit to branch master
in repository api.
commit 4feb2deebe4118468ef75ac0c7ccf52000e660fe
Author: Marcello Stanisci <address@hidden>
AuthorDate: Mon Dec 26 23:22:38 2016 +0100
Fix missing links, commenting out superfluous/outdated section
---
api/api-exchange.rst | 3 +-
api/api-merchant.rst | 8 ++-
api/integration-merchant.rst | 159 ++++++++++++++-----------------------------
3 files changed, 57 insertions(+), 113 deletions(-)
diff --git a/api/api-exchange.rst b/api/api-exchange.rst
index 7f1a151..a0c2368 100644
--- a/api/api-exchange.rst
+++ b/api/api-exchange.rst
@@ -20,7 +20,8 @@ The Exchange RESTful JSON API
=============================
The API specified here follows the :ref:`general conventions <http-common>`
-for all details not specified in the individual requests. The :ref:`glossary`
+for all details not specified in the individual requests.
+The `glossary <https://docs.taler.net/glossary.html#glossary>`
defines all specific terms used in this section.
.. _keys:
diff --git a/api/api-merchant.rst b/api/api-merchant.rst
index 9eccc2f..b2f6123 100644
--- a/api/api-merchant.rst
+++ b/api/api-merchant.rst
@@ -23,7 +23,9 @@
Merchant API
============
-Before reading the API reference documentation, see the :ref:`merchant
architecture<merchant-arch>` and :ref:`payprot`
+Before reading the API reference documentation, see the
+`merchant architecture
<https://docs.taler.net/dev-merchant.html#merchant-arch>`_
+and :ref:`payprot`
---------------------
The Frontend HTTP API
@@ -262,7 +264,7 @@ The following API are made available by the merchant's
`backend` to the merchant
:query wtid: raw wire transfer identifier identifying the wire transfer (a
base32-encoded value)
:query exchange: base URI of the exchange that made the wire transfer
- :query instance: (optional) identificative token of the merchant
:ref:`instance <instances-lab>` which is being tracked.
+ :query instance: (optional) identificative token of the merchant `instance
<https://docs.taler.net/operate-merchant.html#instances-lab>`_ which is being
tracked.
**Response:**
@@ -330,7 +332,7 @@ The following API are made available by the merchant's
`backend` to the merchant
**Request:**
:query id: ID of the transaction we want to trace (an integer)
- :query instance: identificative token for the merchant instance which is to
be tracked (optional). See :ref:`instances-lab`. This information is needed
because the request has to be signed by the merchant, thus we need to pick the
instance's private key.
+ :query instance: identificative token for the merchant instance which is to
be tracked (optional). See
`https://docs.taler.net/operate-merchant.html#instances-lab`_. This information
is needed because the request has to be signed by the merchant, thus we need to
pick the instance's private key.
**Response:**
diff --git a/api/integration-merchant.rst b/api/integration-merchant.rst
index f322161..7cf9304 100644
--- a/api/integration-merchant.rst
+++ b/api/integration-merchant.rst
@@ -203,113 +203,54 @@ parameters to the wallet, which will:
1. Send the payment to `<PAY-URL>` if `<CONTRACT-HASH>` is found in its
database (meaning that the user accepted it).
2. Redirect the browser to `<OFFER-URL>`, if `<CONTRACT-HASH>` is NOT found in
its database, meaning that the user visited a shared fulfillment URL.
---------------------
-Example: Essay Store
---------------------
-
-This section is a high-level description of a merchant :ref:`frontend
<merchant-arch>`,
-and is inspired by our demonstration essay store running at
`https://blog.demo.taler.net/`.
-Basically, it tells how the frontend reacts to clients visiting `offer` and
`fulfillment`
-URLs.
-
-The website is implemented in Python+Flask, and is available at
-https://git.taler.net/merchant-frontends.git/tree/talerfrontends/blog.
-
-The desired effect is that the homepage has a list of buyable articles, and
once the
-user clicks on one of them, they will either get the Taler :ref:`contract
<contract>`
-or a credit card paywall if they have no Taler wallet installed.
-
-In particular, any buyable article on the homepage links to an `offer URL`:
-
-.. sourcecode:: html
-
- <html>
- ...
- <h3><a href="/essay/How_to_write_a_frontend">How to write a
frontend</a></h3>
+..
+ ..................
+ State and security
+ ..................
+
+ The server-side state gets updated in two situations, (1) when an article is
+ "about" to be bought, which means when the user visits the fulfillment URL,
+ and (2) when the user actually pays. For (1), we use the contract hascode to
+ access the state, whereas in (2) we just define a list of payed articles.
+ For example:
+
+ .. sourcecode:: python
+
+ session[<HASHCODE>] = {'article_name': 'How_to_write_a_frontend'} # (1)
+ session['payed_articles'] = ['How_to_write_a_frontend',
'How_to_install_a_backend'] # (2)
+
+ The list of payed articles is used by the frontend to deliver the article to
the user:
+ if the article name is among ``session['payed_articles']``, then the user
gets what they
+ paid for.
+
+ The reason for using `<HASHCODE>` as the key is to prevent the wallet to
send bogus
+ parameters along the fulfillment URL. `<HASHCODE>` is the contract hashcode
that
+ the fulfillment handler gets from the backend using the fulfillment URL
parameters.
+
+ In fact, when the wallet sends the payment to the frontend pay handler, it
has to provide
+ both coins and contract hashcode. That hascode is (1) verified by the
backend when it
+ receives the coins, (2) used by the frontend to update the list of payed
articles.
+
+ See below an example of pay handler:
+
+ .. sourcecode:: python
+
...
- </html>
-
-whence the offer URL design is as follows::
-
- https://<BASEURL>/essay/<ARTICLE-NAME>
-
-`<ARTICLE-NAME>` is just a token that uniquely identifies the article within
the shop.
-
-The server-side handler for the offer URL will return a special page to the
client that
-will either HTTP GET the contract from the frontend, or show the credit card
paywall.
-See `above <offer>`_ how this special page works.
-
-It is interesting to note that the fulfillment URL is just the offer URL plus
-two additional parameters. It looks as follows::
-
-
https://<BASEURL>/essay/<ARTICLE-NAME>?tid=<TRANSACTION-ID>×tamp=<TIMESTAMP>
-
-.. note::
-
- Taler does not require that offer and fulfillment URL have this kind of
relationship.
- In fact, it is perfectly acceptable for the fulfillment URL to be hosted on
a different
- server under a different domain name.
-
-The fulfillment URL server-side handler implements the following logic: it
checks the state
-to see if `<ARTICLE-NAME>` has been payed, and if so, returns the article to
the user.
-If the user didn't pay, then it `executes` the contract by returning a special
page to the
-browser. The contract execution is the order to pay that the frontend gives to
the wallet.
-
-Basically, the frontend points the wallet to the hashcode of the contract
which is to be paid
-and the wallet responds by giving coins to the frontend. Because the frontend
doesn't perform
-any cryptographic work by design, it forwards `<ARTICLE-NAME>`,
`<TRANSACTION-ID>` and
-`<TIMESTAMP>` to the frontend in order to get the contract's hashcode.
-
-See `above <fulfillment>`_ for a detailed description of how the frontend
triggers the
-payment in the wallet.
-
-..................
-State and security
-..................
-
-The server-side state gets updated in two situations, (1) when an article is
-"about" to be bought, which means when the user visits the fulfillment URL,
-and (2) when the user actually pays. For (1), we use the contract hascode to
-access the state, whereas in (2) we just define a list of payed articles.
-For example:
-
-.. sourcecode:: python
-
- session[<HASHCODE>] = {'article_name': 'How_to_write_a_frontend'} # (1)
- session['payed_articles'] = ['How_to_write_a_frontend',
'How_to_install_a_backend'] # (2)
-
-The list of payed articles is used by the frontend to deliver the article to
the user:
-if the article name is among ``session['payed_articles']``, then the user gets
what they
-paid for.
-
-The reason for using `<HASHCODE>` as the key is to prevent the wallet to send
bogus
-parameters along the fulfillment URL. `<HASHCODE>` is the contract hashcode
that
-the fulfillment handler gets from the backend using the fulfillment URL
parameters.
-
-In fact, when the wallet sends the payment to the frontend pay handler, it has
to provide
-both coins and contract hashcode. That hascode is (1) verified by the backend
when it
-receives the coins, (2) used by the frontend to update the list of payed
articles.
-
-See below an example of pay handler:
-
-.. sourcecode:: python
-
- ...
-
- # 'deposit_permission' is the JSON object sent by the wallet
- # which contains coins and the contract hashcode.
- response = send_payment_to_backend(deposit_permission)
-
- # The backend accepted the payment
- if 200 == response.status_code:
- # Here we pick the article name from the state defined at
- # fulfillment time.
- # deposit_permission['H_contract'] is the contract hashcode
- payed_article = session[deposit_permission['H_contract']]['article_name']
- session['payed_articles'].append(payed_article)
-
-
-So the wallet is forced to send a valid contract hashcode along the payment,
-and since that hashcode is then used to update the list of payed articles,
-the wallet is forced to send fulfillment URL parameters that match that
hashcode,
-therefore being valid parameters.
+
+ # 'deposit_permission' is the JSON object sent by the wallet
+ # which contains coins and the contract hashcode.
+ response = send_payment_to_backend(deposit_permission)
+
+ # The backend accepted the payment
+ if 200 == response.status_code:
+ # Here we pick the article name from the state defined at
+ # fulfillment time.
+ # deposit_permission['H_contract'] is the contract hashcode
+ payed_article =
session[deposit_permission['H_contract']]['article_name']
+ session['payed_articles'].append(payed_article)
+
+
+ So the wallet is forced to send a valid contract hashcode along the payment,
+ and since that hashcode is then used to update the list of payed articles,
+ the wallet is forced to send fulfillment URL parameters that match that
hashcode,
+ therefore being valid parameters.
--
To stop receiving notification emails like this one, please contact
address@hidden
- [GNUnet-SVN] [taler-api] 04/22: Still on splitting, (continued)
- [GNUnet-SVN] [taler-api] 04/22: Still on splitting, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 07/22: Nothing but APIs under api.taler.net, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 21/22: Removing trailing .rst from imported files, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 03/22: Splitting BUILDIR, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 20/22: Reverting previous (test) commit, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 22/22: Merge branch 'split' of ssh://taler.net/api into split, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 18/22: Minor fixes on rendering, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 08/22: Minor fixes on rendering, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 14/22: Still on splitting, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 17/22: Nothing but APIs under api.taler.net, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 15/22: Fix missing links, commenting out superfluous/outdated section,
gnunet <=
- [GNUnet-SVN] [taler-api] 11/22: Proof-reading blog example page, gnunet, 2017/01/27
- [GNUnet-SVN] [taler-api] 13/22: Splitting BUILDIR, gnunet, 2017/01/27