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 <snoopd...@apache.org> Authored: Wed Aug 5 08:48:21 2015 -0400 Committer: Dave Johnson <snoopd...@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:
