Merge pull request #16 from bigchaindb/feat/15/add-persisted-id-to-pa…

…yload

Add persisted id to payload

README.md

@@ -192,13 +192,13 @@ PAYLOAD:
 RETURNS:
 {
     "work": {
-        "@id": "<currently empty>",
+        "@id": "<Relative URI with the ID of the entity on BigchainDB>",
         "@type": "CreativeWork",
         "name": "The Lord of the Rings Trilogy",
         "author": "J. R. R. Tolkien"
     },
     "manifestation": {
-        "@id": "<currently empty>",
+        "@id": "<Relative URI with the ID of the entity on BigchainDB>",
         "@type": "CreativeWork"
         "name": "The Fellowship of the Ring",
         "manifestationOfWork": "<URI pointing to the Work's transaction ../<txid>",
@@ -207,20 +207,28 @@ RETURNS:
         "isManifestation": true
     },
     "copyright": {
-        "@id": "<currently empty>",
+        "@id": "<Relative URI with the ID of the entity on BigchainDB>",
         "@type": "Copyright"
         "rightsOf": "<Relative URI pointing to the Manifestation ../<txid>"
     }
 }
 ```
 
-#### Why is `@id` currently empty?
+#### What are the returned `@id`s?
 
-An empty `@id` resolves the entity's URI to be the current document base (i.e.
-URL). While this is not particularly true, as requesting the creation
-transaction of an entity results in much more than just the entity, this is the
-implementation for now. In the future, we're planning to replace JSON-LD's URI
-linking structure with [IPLD](https://github.com/ipld/specs).
+The returned `@id`s denote the persisted ID of the entities on BigchainDB as a
+relative URI to the current document base (i.e. the route URL, or
+`/manifestations` in this case). For now, these point to the `CREATE`
+transaction for the entity; in the future, they will be changing to be an asset
+ID instead.
+
+In the case of the returned Work and Copyright, their `@id`s are slightly
+inconvenient to process as they live under a different base URL (`/works` and
+`/rights`, respectively). You should strip away the leading paths to use just
+the persisted IDs of these entities.
+
+Note that in the future, we also plan to replace the JSON-LD linking structure
+with [IPLD](https://github.com/ipld/specs).
 
 #### Was my POST to `/manifestations/` successful?
 
@@ -232,13 +240,14 @@ To check if your POST was successful, try validating by doing the following:
 or
 
 1. Open your browser and go to `http://localhost:9984/api/v1` (your locally
-   running BigchainDB instance - if using Docker, use port `32768`).
+   running BigchainDB instance - if using the default Docker settings, use port
+   `32768` instead).
 
-1. To check if your previously created models were included in BigchainDB, take
-   the string in `manifestationOfWork` or `rightsOf` and append it to the
-   following link: `http://localhost:9984/api/v1/transactions/<string goes here>`.
-   BigchainDB should then answer with the transaction, the model was registerd
-   in (if using Docker, use port `32768`).
+1. To check if your previously created entities were included in BigchainDB,
+   take the string in any of the returned `@id`s and append it to the following
+   link: `http://localhost:9984/api/v1/transactions/<string goes here>`.
+   BigchainDB should then answer with the transaction the entity was registered
+   in (if using the default Docker settings, use port `32768` instead).
 
 **Note**: If running on Docker and/or Docker Machine, substitute the hostnames
 and ports of the above URLs with your Docker settings, as necessary (see the
@@ -278,7 +287,7 @@ PAYLOAD:
 RETURNS:
 {
     "right": {
-        "@id": "<currently empty>",
+        "@id": "<Relative URI with the ID of the entity on BigchainDB>",
         "@type": "Right",
         "allowedBy": <The sourceRightId>,
         "license": "<Legal license text or URI pointing to a license document>",

tests/test_api.py

@@ -28,14 +28,12 @@ def test_create_manifestation(client, user):
         'work': {
             '@context': ['<coalaip placeholder>', 'http://schema.org/'],
             '@type': 'CreativeWork',
-            '@id': '',
             'name': 'The Lord of the Rings Triology',
             'author': 'J. R. R. Tolkien',
         },
         'manifestation': {
             '@context': ['<coalaip placeholder>', 'http://schema.org/'],
             '@type': 'CreativeWork',
-            '@id': '',
             'name': 'The Fellowship of the Ring',
             'datePublished': '29-07-1954',
             'url': 'http://localhost/lordoftherings.txt',
@@ -44,17 +42,31 @@ def test_create_manifestation(client, user):
         'copyright': {
             '@context': ['<coalaip placeholder>', 'http://schema.org/'],
             '@type': 'Copyright',
-            '@id': '',
         },
     }
     resp = client.post(url_for('manifestation_views.manifestationapi'),
                        data=json.dumps(payload),
                        headers={'Content-Type': 'application/json'})
     resp_dict = resp.json
-    assert bool(resp_dict['copyright']['rightsOf']) is True
-    assert bool(resp_dict['manifestation']['manifestationOfWork']) is True
+    copyright_ = resp_dict['copyright']
+    manifestation = resp_dict['manifestation']
+    work = resp_dict['work']
+
+    assert bool(copyright_['rightsOf']) is True
+    assert bool(manifestation['manifestationOfWork']) is True
+
+    # Check @ids
+    assert copyright_['@id'].startswith('../rights/')
+    assert bool(copyright_['@id'].strip('../rights/')) is True
+    assert bool(manifestation['@id']) is True
+    assert work['@id'].startswith('../works/')
+    assert bool(work['@id'].strip('../works/')) is True
+
     resp_dict['copyright'].pop('rightsOf')
     resp_dict['manifestation'].pop('manifestationOfWork')
+    resp_dict['copyright'].pop('@id')
+    resp_dict['manifestation'].pop('@id')
+    resp_dict['work'].pop('@id')
     assert resp_dict == expected
     assert resp.status_code == 200
 
@@ -110,7 +122,6 @@ def test_create_right(client, user):
         'right': {
             '@context': ['<coalaip placeholder>', 'http://schema.org/'],
             '@type': 'Right',
-            '@id': '',
             'allowedBy': payload['sourceRightId'],
             'license': 'http://www.ascribe.io/terms',
         }
@@ -119,8 +130,12 @@ def test_create_right(client, user):
     resp = client.post(url_for('right_views.rightapi'),
                        data=json.dumps(payload),
                        headers={'Content-Type': 'application/json'})
+    resp_dict = resp.json
+    assert bool(resp_dict['right']['@id']) is True
+
+    resp_dict['right'].pop('@id')
+    assert resp_dict == expected
     assert resp.status_code == 200
-    assert resp.json == expected
 
 
 def test_create_right_missing_single_attribute(client, user):

web/views/manifestations.py

@@ -33,16 +33,20 @@ def post(self):
             'signing_key': copyright_holder.pop('signingKey')
         }
 
-        copyright, manifestation, work = coalaip.register_manifestation(
+        copyright_, manifestation, work = coalaip.register_manifestation(
             manifestation_data=manifestation,
             copyright_holder=copyright_holder,
             work_data=work)
 
-        res = {
-            'manifestation': manifestation.to_jsonld(),
-            'work': work.to_jsonld(),
-            'copyright': copyright.to_jsonld()
-        }
+        # Add the appropraite @id to the JSON-LD
+        res = {}
+        for (entity, id_template, key) in [
+                (copyright_, '../rights/{}', 'copyright'),
+                (manifestation, '{}', 'manifestation'),
+                (work, '../works/{}', 'work')]:
+            ld_data = entity.to_jsonld()
+            ld_data['@id'] = id_template.format(entity.persist_id)
+            res[key] = ld_data
 
         return res
 

web/views/rights.py

@@ -35,7 +35,9 @@ def post(self):
         right = coalaip.derive_right(right_data=right,
                                      current_holder=current_holder)
 
-        res = {'right': right.to_jsonld()}
+        right_jsonld = right.to_jsonld()
+        right_jsonld['@id'] = right.persist_id
+        res = {'right': right_jsonld}
 
         return res