usergrid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From snoopd...@apache.org
Subject incubator-usergrid git commit: Converted Assets & Files section to markdown.
Date Wed, 05 Aug 2015 12:48:36 GMT
Repository: incubator-usergrid
Updated Branches:
  refs/heads/ug2-doc-update d7bae265d -> d00ebf968


Converted Assets & Files section to markdown.


Project: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/commit/d00ebf96
Tree: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/tree/d00ebf96
Diff: http://git-wip-us.apache.org/repos/asf/incubator-usergrid/diff/d00ebf96

Branch: refs/heads/ug2-doc-update
Commit: d00ebf968393c0029ce5597cffefeedcb4be56a5
Parents: d7bae26
Author: Dave Johnson <snoopdave@apache.org>
Authored: Wed Aug 5 08:48:21 2015 -0400
Committer: Dave Johnson <snoopdave@apache.org>
Committed: Wed Aug 5 08:48:21 2015 -0400

----------------------------------------------------------------------
 docs/asset-and-files/folders.md              | 85 ++++++++++++++++++++++
 docs/asset-and-files/legacy-asset-support.md |  0
 docs/asset-and-files/retrieving-assets.md    | 27 +++++++
 docs/asset-and-files/tbd.md                  |  1 -
 docs/asset-and-files/uploading-assets.md     | 86 +++++++++++++++++++++++
 docs/index.rst                               |  4 +-
 6 files changed, 201 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/asset-and-files/folders.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/folders.md b/docs/asset-and-files/folders.md
new file mode 100644
index 0000000..7c425be
--- /dev/null
+++ b/docs/asset-and-files/folders.md
@@ -0,0 +1,85 @@
+# Folders
+
+## Linking a folder to an asset
+In order to access the asset for the image in the folder, you need to link the folder to
the asset. You can do that by issuing a POST request in the following format:
+
+    POST /{org-uuid}/{app-uuid}/folders/{folder-uuid}/assets/{assets_id}
+    
+where ``{folder-uuid}`` is the UUID of the folder, and ``{assets-uuid}`` is the UUID of the
assets entity.
+
+Here’s how you could link the folder and the asset you created for the my-image.jpg image:
+
+    POST https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b

+    
+In the response, you should see the assets entity for the image added to the folder:
+
+    {
+      "action": "post",
+      "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+      "params": {},
+      "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+      "uri": "https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+      "entities": [
+        {
+          "uuid": "9501cda1-2d21-11e2-b4c6-02e81ac5a17b",
+          "type": "asset",
+          "name": "my-image.jpg",
+          "created": 1352763303163,
+          "modified": 1352763303163,
+          "metadata": {
+            "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/9501cda1-2d21-11e2-b4c6-02e81ac5a17b"
+          },
+          "owner": "5c0c1789-d503-11e1-b36a-12313b01d5c1",
+          "path": "/myassets/asset1"
+        }
+      ],
+      "timestamp": 1352830448045,
+      "duration": 54,
+      "organization": "my-org”,
+      "applicationName": "my-app"
+    }
+    
+## Retrieve list of folder assets
+You can also request a list of the linked contents of the folder like this:
+
+    GET https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets
+    
+The response should look something like this:
+
+    {
+      "action": "get",
+      "application": "3400ba10-cd0c-11e1-bcf7-12313d1c4491",
+      "params": {
+        "_": [
+          "1352830364891"
+        ]
+      },
+      "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+      "uri": "https://api.usergrid.com/my-org/my-app/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets",
+      "entities": [
+        {
+          "uuid": "7bf47435-2ac8-11e2-b4c6-02e81ac5a17b",
+          "type": "asset",
+          "name": "my-image.jpg",
+          "created": 1352505133598,
+          "modified": 1352507245108,
+          "checksum": "8e0cd3866ee20746c99e9a9825f38ad8",
+          "content-length": 11853,
+          "content-type": "image/jpeg",
+          "etag": "\"8e0cd3866ee20746c99e9a9825f38ad8\"",
+          "metadata": {
+            "connecting": {
+              "assets": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/7bf47435-2ac8-11e2-b4c6-02e81ac5a17b/connecting/assets"
+            },
+            "connection": "assets",
+            "path": "/folders/6640a601-2ac6-11e2-92c3-02e81ae640dc/assets/7bf47435-2ac8-11e2-b4c6-02e81ac5a17b"
+          },
+          "owner": "5c0c1789-d503-11e1-b36a-12313b01d5c1",
+          "path": "my-image"
+        }
+      ],
+      "timestamp": 1352830363797,
+      "duration": 57,
+      "organization": "my-org",
+      "applicationName": "my-app"
+    }

http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/asset-and-files/legacy-asset-support.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/legacy-asset-support.md b/docs/asset-and-files/legacy-asset-support.md
new file mode 100644
index 0000000..e69de29

http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/asset-and-files/retrieving-assets.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/retrieving-assets.md b/docs/asset-and-files/retrieving-assets.md
new file mode 100644
index 0000000..9313ae8
--- /dev/null
+++ b/docs/asset-and-files/retrieving-assets.md
@@ -0,0 +1,27 @@
+# Retrieving assets
+
+## Retrieving asset data
+
+To retrieve the asset from an entity, send a ``GET`` request with the ``Accept`` header set
to the content type of the asset. The content type can be retrieved from the ``file-metadata.content-type``
property of the entity the asset is attached to.
+
+### Request syntax
+
+    curl -X GET -H 'Accept: <content_type>' 'https://api.usergrid.com/<org>/<app>/<collection>/<entity>
+
+Parameters
+
+Parameter	     Description
+---------        -----------
+content_type	 The content type of the attached asset. For example, text/plain, image/jpeg.
+org	Organization UUID or organization name
+app	Application  UUID or application name
+collection	     Name or UUID of the collection of the entity the asset is attached to.
+entity	         Name or UUID of the entity the asset is attached to.
+
+### Example request
+The following request will retrieve the data for a jpeg file attached to an entity named
'cloud' in the 'pictures' collection:
+
+    curl -X GET -H 'Accept: image/jpeg' 'https://api.usergrid.com/your-org/your-app/pictures/cloud
+    
+## Retrieving an asset entity
+To retrieve the entity that an asset is attached to, perform a ``GET`` request as you normally
would to retrieve an entity. For more information, see [Retrieving Data Entities](../data-storage/entities.html#retrieving-data-entities).
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/asset-and-files/tbd.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/tbd.md b/docs/asset-and-files/tbd.md
deleted file mode 100644
index 279d128..0000000
--- a/docs/asset-and-files/tbd.md
+++ /dev/null
@@ -1 +0,0 @@
-# COMING SOON...
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/asset-and-files/uploading-assets.md
----------------------------------------------------------------------
diff --git a/docs/asset-and-files/uploading-assets.md b/docs/asset-and-files/uploading-assets.md
new file mode 100644
index 0000000..e50e909
--- /dev/null
+++ b/docs/asset-and-files/uploading-assets.md
@@ -0,0 +1,86 @@
+# Uploading assets
+
+Using Apigee's API BaaS, you can store and retrieve files and assets that hold data objects
such as images, video, and audio content.
+
+API BaaS manages these objects as Asset entities. Optionally, you can use Folder entities
to organize related assets.
+
+## Uploading assets
+Assets can be any file type and can be attached to any entity. When an asset is uploaded,
API BaaS will automatically detect the file metadata for the asset and save it in the associated
entity as a ``file-metadata`` property. Only 1 asset can be attached to an entity.
+
+To attach an asset to an entity, do the following:
+
+### Request syntax
+
+    curl -X POST -F name='<filename>' -F file=@<file_location> 'https://api.usergrid.com/<org>/<app>/<collection>/<entity>
+    
+Parameters
+
+Parameter	        Description
+---------           -----------
+filename	        A filename to associate with the asset.
+file_location	    The location of the asset to be uploaded.
+org	Organization    UUID or organization name
+app	Application     UUID or application name
+collection	        Name or UUID of the collection of the entity you want to attach the asset
to.
+entity	            Name or UUID of an existing entity you want to attach the asset to.
+
+### Example request
+
+    curl -X POST -i -F name='clouds' -F file=@happy_clouds.jpg 'https://api.usergrid.com/your-org/your-app/pictures/'
+    
+### Example response
+
+Notice the ``file-metadata`` property in the response.
+
+    {
+        "action" : "post",
+        "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
+        "params" : { },
+        "path" : "/users",
+        "uri" : "https://api.usergrid.com/amuramoto/sandbox/pictures",
+        "entities" : [ {
+        "uuid" : "410b213a-b379-11e3-a0e5-9953085ea376",
+        "type" : "user",
+        "name" : "test",
+        "created" : 1395681911491,
+        "modified" : 1399069838919,
+        "name" : "clouds",    
+        "file" : "fobnszewobnioerabnoiawegbrn\n",
+        "file-metadata" : {
+          "content-type" : "image/jpeg",
+          "etag" : "\"2e1db7299b0a667ed80e674a0ef9d653\"",
+          "last-modified" : 1399070010115,
+          "content-length" : 28,
+          "checksum" : "2e1db7299b0a667ed80e674a0ef9d653"
+        },
+        "metadata" : {
+          "connecting" : {        
+            "likes" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/connecting/likes"
+          },
+          "path" : "/users/410b213a-b379-11e3-a0e5-9953085ea376",
+          "sets" : {
+            "rolenames" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
+            "permissions" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/permissions"
+          },
+          "connections" : {
+            "follows" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/follows"
+          },
+          "collections" : {
+            "activities" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/activities",
+            "devices" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/devices",
+            "feed" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/feed",
+            "groups" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/groups",
+            "roles" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/roles",
+            "following" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/following",
+            "followers" : "/users/410b213a-b379-11e3-a0e5-9953085ea376/followers"
+          }
+        }
+        } ],
+        "timestamp" : 1399070009986,
+        "duration" : 441,
+        "organization" : "your-org",
+        "applicationName" : "your-app"
+    }
+
+## Updating assets
+To update the data for an asset, perform the same request outlined above in 'Uploading assets'
as a ``PUT`` request rather than a ``POST``.

http://git-wip-us.apache.org/repos/asf/incubator-usergrid/blob/d00ebf96/docs/index.rst
----------------------------------------------------------------------
diff --git a/docs/index.rst b/docs/index.rst
index b68cf36..c3b6a13 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -98,7 +98,9 @@ Apache Usergrid Documentation
    :maxdepth: 2
    :caption: Assets & Files
   
-   asset-and-files/tbd
+   asset-and-files/uploading-assets.md
+   asset-and-files/retrieving-assets.md
+   asset-and-files/folders.md
    
 .. _counters-and-events:
 


Mime
View raw message