Merge pull request #472 from bigchaindb/move-python-server-api-examples

Docs: moved The Python Server API by Example under Drivers & Clients

docs/source/drivers-clients/http-client-server-api.rst

@@ -1,7 +1,7 @@
 The HTTP Client-Server API
 ==========================
 
-Note: The HTTP client-server API is currently quite rudimentary. For example, there is no ability to do complex queries using the HTTP API. We plan to add querying capabilities in the future. If you want to build a full-featured proof-of-concept, we suggest you use :doc:`the Python Server API <../nodes/python-server-api-examples>` for now.
+Note: The HTTP client-server API is currently quite rudimentary. For example, there is no ability to do complex queries using the HTTP API. We plan to add querying capabilities in the future. If you want to build a full-featured proof-of-concept, we suggest you use :doc:`the Python Server API <../drivers-clients/python-server-api-examples>` for now.
 
 When you start Bigchaindb using `bigchaindb start`, an HTTP API is exposed at the address stored in the BigchainDB node configuration settings. The default is for that address to be:
 

docs/source/drivers-clients/index.rst

@@ -7,6 +7,7 @@ BigchainDB Drivers & Clients
 .. toctree::
    :maxdepth: 1
 
+   python-server-api-examples
    http-client-server-api
    python-driver-api-examples
    example-apps

docs/source/drivers-clients/python-server-api-examples.md

@@ -1,10 +1,11 @@
 # The Python Server API by Example
 
-This section gives an example of using the Python Server API to interact _directly_ with a BigchainDB node running BigchainDB Server. That is, in this example, the Python code and BigchainDB Server run on the same machine.
+**Currently, the HTTP Client-Server API is very rudimentary, so you may want to use the Python Server API to develop prototype clients and applications, for now. Keep in mind that in the future, clients will only be able to use the HTTP Client-Server API (and possibly other Client-Server APIs) to communicate with BigchainDB nodes.**
 
-(One can also interact with a BigchainDB node via other APIs, including the HTTP Client-Server API.)
+This section has examples of using the Python Server API to interact _directly_ with a BigchainDB node running BigchainDB Server. That is, in these examples, the Python code and BigchainDB Server run on the same machine.
+
+One can also interact with a BigchainDB node via other APIs, including the HTTP Client-Server API.
 
-We create a digital asset, sign it, write it to a BigchainDB Server instance, read it, transfer it to a different user, and then attempt to transfer it to another user, resulting in a double-spend error.
 
 ## Getting Started
 
@@ -32,6 +33,7 @@ In a federation of BigchainDB nodes, each node has its own `Bigchain` instance.
 
 The `Bigchain` class is the main API for all BigchainDB interactions, right now. It does things that BigchainDB nodes do, but it also does things that BigchainDB clients do. In the future, it will be refactored into different parts. The `Bigchain` class is documented [elsewhere (link)](../appendices/the-Bigchain-class.html).
 
+
 ## Create a Digital Asset
 
 At a high level, a "digital asset" is something which can be represented digitally and can be assigned to a user. In BigchainDB, users are identified by their public key, and the data payload in a digital asset is represented using a generic [Python dict](https://docs.python.org/3.4/tutorial/datastructures.html#dictionaries).

docs/source/nodes/index.rst

@@ -13,4 +13,3 @@ BigchainDB Nodes
    running-unit-tests
    configuration
    bigchaindb-cli
-   python-server-api-examples

docs/source/quickstart.md

@@ -35,4 +35,4 @@ bigchaindb start
 
 That's it!
 
-For now, you can get a good sense of how to work with BigchainDB by going through [the examples in the section on the Python Server API](nodes/python-server-api-examples.html).
+For now, you can get a good sense of how to work with BigchainDB by going through [the examples in the section on the Python Server API](drivers-clients/python-server-api-examples.html).

docs/source/topic-guides/smart-contracts.md

@@ -1,3 +1,3 @@
 # BigchainDB and Smart Contracts
 
-BigchainDB isn’t intended for running smart contracts. That said, it can do many of the things that smart contracts are used to do. For example, the owners of an asset can impose conditions that must be fulfilled by anyone wishing to transfer the asset to new owners; see the [section on conditions](models.html#conditions-and-fulfillments). BigchainDB also [supports a form of escrow](../nodes/python-server-api-examples.html#escrow).
+BigchainDB isn’t intended for running smart contracts. That said, it can do many of the things that smart contracts are used to do. For example, the owners of an asset can impose conditions that must be fulfilled by anyone wishing to transfer the asset to new owners; see the [section on conditions](models.html#conditions-and-fulfillments). BigchainDB also [supports a form of escrow](../drivers-clients/python-server-api-examples.html#escrow).