The service provides the file storage and management abstraction on top of the variety of possible storage platforms ranging from internal platform resources, to cloud services such as Amazon S3, to even user-tailored solutions such as Dropbox.

Specifically, the client applications will

1. register the new client and appId in the developer console (section “Own resources” of the file storage service permissions). This is necessary in order to scope the access to a specific app storage.
2. define the type storage they want to exploit and provide the necessary registration information associated to the storage.
3. register user accounts associated to the client app and the storage
4. perform file management operations on behalf of the user: upload files, read files, read metadata, update and delete files.

The storage registration and user account registration strictly depends on the storage type. In particular, in certain cases the involvement of the end user will be required to grant the consent to the application to manage the user's data. This is the case, for example, for Dropbox, so that the user is asked a permission to access a particular folder in her Dropbox storage.

An important feature of the storage is that it relies on the Social Service in order to enable file sharing across the user's social network.

Consequently, the storage relies on the following data structures:

• Storage account to hold the application storage registration information
• User account to associate the user to the application and the storage
• File metadata to hold relevant information about the files, such as their ids, entity ID (necessary by the social service for, e.g., sharing), etc.

Currently, the only storage type supported is 'Dropbox', where the files are storage in a folder within the user's Dropbox account. This indeed requires the user to have Dropbox account and the sufficient space to store the files.

• Storage: represent the application storage registration information.
  • id: unique identifier of the storage account (string)
  • appId: application identifier as registered in the Developer Console for the file storage service.
  • name: name of the storage account.
  • storageType: specifies the target platform used for file storage (currently, only DROPBOX is allowed).
  • redirect: when the storage is tailored to the user (e.g., Dropbox), an explicit authorization procedure is needed to generate the user account. This parameter is used to redirect the result of the account creation to the client application server-side.
  • configurations: list of storage-specific configuration properties necessary to access the storage. The specific properties depend on the storage type. Each configuration is represent with
    • name: configuration property name (string)
    • value: configuration property value (string)
• Account: represent the user registration associated to the app storage.
  • id: account unique identifier
  • userId: user ID
  • appId: application identifier of the app storage
  • storageType: type of the storage
  • name: name of the user account
  • configurations: list of storage-specific user properties necessary to access the storage on behalf of the user. The specific properties depend on the storage type. Each configuration is represent with
    • name: configuration property name (string)
    • value: configuration property value (string)
  • Metadata: stored file descriptor with
    • resourceId: unique identifier of the resource
    • name: file name
    • socialId: file identifier for the Social Servce
    • fileExternalId: optional identifier of the resource given by the storage
    • accountId: identifier of the user account
    • appId: identifier of the app managing the storage
    • contentType: MIME type of the resource
    • size: size of the resource (in bytes)
    • creationTs: timestamp of the resource creation
    • lastModifiedTs: timestamp of the resource update
  • Resource: the file itself with
    • id: file identifier
    • name: file name
    • content: byte array of the file content
    • contentType: MIME type of the file
  • Token: contains all the information to download a resource from the storage. Depending on the storage type, different properties may be required, including
    • url: the address to download the file from
    • methodREST: HTTP method to use for download (string)
    • httpHeaders: optional map of headers to be added to the request for the file to be downloaded
    • metadata: optional auxiliary properties necessary for the file retrieval.
    • storageType: type of the storage operating the file

To start using the file storage service, the client app should be registered using the developer console. Additionally, it should have necessary permissions for storage management, user account management, and the file management. This is achieved by declaring its own appId in the section “Own resources” of the file storage service permissions. This is necessary in order to scope the access to a specific app storage. The value is unique across all the SmartCommunity apps.

File management flow consists of the following steps: app storage registration, user account registration, and the file operations.

In this step the application should register its own storage configuration. Depending on the storage type the configuration may contain various elements, specific to the storage type. The storage configuration may be then updated if necessary.

The storage operations require the corresponding appId value as registered in the developer console. This is used as a unique identifier of the application storage and also for protecting the storage from unauthorized access.

Different storage types may require specific attributes assigned. Below we enumerate the specific attributes for the supported storage types

Before the user performs the operations on the file storage, it is necessary to register the user account for app storage. The account associates the user to the app storage, and allows for scoping the read/write operations respectively.

The user account registration depends on the storage type. In particular, in case of simple storage where the access is granted to a registered app and not to its users (e.g., internal storage or the one like Amazon S3), the registration is accomplished using the corresponding REST service. In case of an external storage that requires the user authorization for the client apps to perform operations (e.g., Dropbox, Google Drive, etc.), the procedure is more complex. In this case a complex Web-based protocol requiring user interactions may be necessary. Specifically, such an authorization procedure contains the following steps:

• acquisition (via REST service) of the authorization URL that will start the authorization flow;
• execution of the flow in the client browser or an embedded browser of a mobile app. The authorization flow may involve the external storage authorization as well;
• redirect to a success page with the information about the account registration outcome. This is especially important when the service is used in a web application as at this step the procedure returns to the application page. Note that for this to happen, the redirect URI should be registered with the storage.

See below for the details of the authorization flow and endpoints.

Once the user is registered, the client app may perform the file management operations on behalf of the user. Specifically, it is possible to

• upload a file.
• modify a file.
• delete a file.
• read file metadata information.
• obtain the resource access token. This provides all the necessary information (URL, HTTP method, HTTP headers) to access the resource over the network. Note that the access is granted to the resource owners or if the resource was shared with the user.

The requests are emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.filestorage

Besides the REST endpoint that is exposed for the storage configuration management, there exist a Web page that facilitates the creation/update of the storage configuration. The endpoint is available at

https://dev.smartcommunitylab.it/core.filestorage/conf/storage

and allows to manually set the storage parameters. To perform the operation the form requires the appId and the client token. The latter may be obtained via Developer Console.

This operation allows for storing the app storage parameters. Depending on the storage type, variety of specific configuration parameters should be provided. Also, in case of external storage that requires user authorization, the redirect URL may be specified.

Permission

filestorage.storage.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• request body: storage profile data structure

Request

POST /core.filestorage/storage/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
   "appId":"myApp",
   "name":"Sample storage",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"APP_KEY",
         "value":"123"
      },
      {
         "name":"APP_SECRET",
         "value":"456"
      }
   ]
}

Response

{
   "id":"521a66c8d3a19009492c4405",
   "appId":"myApp",
   "name":"Sample storage",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"APP_KEY",
         "value":"123"
      },
      {
         "name":"APP_SECRET",
         "value":"456"
      }
   ]
}

Update the storage configuration.

Permission

filestorage.storage.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• request body: storage profile data structure

Request

PUT /core.filestorage/storage/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
   "id":"521a66c8d3a19009492c4405",
   "appId":"myApp",
   "name":"Sample storage",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"APP_KEY",
         "value":"123"
      },
      {
         "name":"APP_SECRET",
         "value":"456"
      }
   ]
}

Response

{
   "id":"521a66c8d3a19009492c4405",
   "appId":"myApp",
   "name":"Sample storage",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"APP_KEY",
         "value":"123"
      },
      {
         "name":"APP_SECRET",
         "value":"456"
      }
   ]
}

Delete the app storage profile.

Permission

filestorage.storage.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app

Request

DELETE /core.filestorage/storage/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: operation outcome (boolean)

Read the storage configuration.

Permission

filestorage.storage.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app

Request

GET /core.filestorage/storage/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "id":"521a66c8d3a19009492c4405",
   "appId":"myApp",
   "name":"Sample storage",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"APP_KEY",
         "value":"123"
      },
      {
         "name":"APP_SECRET",
         "value":"456"
      }
   ]
}

In case of the storage that requires explicit user authorization in order to access its functionality, the flow of activities consists of the following steps.

Obtain the authorization URL to be called to obtain the user consent for the storage. The operation is performed with the user credentials.

The request is emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.filestorage

Parameters

• appId (path variable): application ID as registered in the developer console for this app

Request

GET /core.filestorage/requestAuth/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

https://dev.smartcommunitylab.it/core.filestorage/authorize/44242ffsf45434534

Using the provided URL the authorization flow is initiated. The URL should be opened in a browser (i.e., by the JavaScript client-side) or in an embedded browser of the mobile app.

Upon completion, the procedure redirects to either the service URL or to the address specified in the storage configuration under redirect parameter.

https://dev.smartcommunitylab.it/core.filestorage/authorize/done?status=ok&accountId=1234567

In case of an error or if the user has negated the access, the status will return error value and error_message parameter will provide the information about the problem.

At this phase, the account is created and stored server-side.

Using the account read operations it is possible to access the newly created user account and/or start performing the file management operations for that account.

The requests are emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.filestorage

This operation allows for registering an account for an arbitrary user. Depending on the storage type, variety of specific configuration parameters may be provided.

Permission

filestorage.account.app.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• request body: account data structure

Request

POST /core.filestorage/account/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

This operation allows for updating an account for an arbitrary user.

Permission

filestorage.account.app.{appId}

Parameters:

• accountId (path variable): account ID
• appId (path variable): application ID as registered in the developer console for this app
• request body: account data structure

Request

PUT /core.filestorage/account/app/{appId}/{accountId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

This operation allows for deleting an account for an arbitrary user.

Permission

filestorage.account.app.{appId}

Parameters:

• accountId (path variable): account ID
• appId (path variable): application ID as registered in the developer console for this app

Request

DELETE /core.filestorage/account/app/{appId}/{accountId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: operation outcome (boolean)

This operation allows for reading an account for an arbitrary user.

Permission

filestorage.account.app.{appId}

Parameters:

• accountId (path variable): account ID
• appId (path variable): application ID as registered in the developer console for this app

Request

GET /core.filestorage/account/app/{appId}/{accountId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

This operation allows for reading accounts for all users.

Permission

filestorage.account.app.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app

Request

GET /core.filestorage/account/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "accounts": [
   {
      "id":"521a6f0bd3a19009492c4407",
      "userId":"1",
      "name":"Sample account 1377463947490",
      "storageType":"DROPBOX",
      "configurations":[
         {
            "name":"USER_KEY",
            "value":"123"
         },
         {
            "name":"USER_SECRET",
            "value":"456"
         }
      ],
      "appId":"test"
   },
   ...
   ]

This operation allows for registering an account for the currently signed user. Depending on the storage type, variety of specific configuration parameters may be provided.

Permission

filestorage.account.user.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• request body: account data structure

Request

POST /core.filestorage/account/user/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

This operation allows for updating an account for the currently signed user.

Permission

filestorage.account.user.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• request body: account data structure

Request

PUT /core.filestorage/account/user/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

This operation allows for deleting an account for the currently signed user.

Permission

filestorage.account.user.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app

Request

DELETE /core.filestorage/account/user/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response: operation outcome (boolean)

This operation allows for reading an account for the currently signed user.

Permission

filestorage.account.user.{appId}

Parameters:

• appId (path variable): application ID as registered in the developer console for this app

Request

GET /core.filestorage/account/user/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
   "id":"521a6f0bd3a19009492c4407",
   "userId":"1",
   "name":"Sample account 1377463947490",
   "storageType":"DROPBOX",
   "configurations":[
      {
         "name":"USER_KEY",
         "value":"123"
      },
      {
         "name":"USER_SECRET",
         "value":"456"
      }
   ],
   "appId":"test"
}

The requests are emitted to the following endpoint:

https://dev.smartcommunitylab.it/core.filestorage

This operation allows for uploading a file for the specified account. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.resource.app.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• accountId (path variable): user account ID
• file (multipart request param): file attached
• createSocialData: if the social entity should be automatically created and assigned to this file. Defaults to true

Request

POST /core.filestorage/resource/create/app/{appId}/{accountId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

?createSocialData=false

Response

{
   "name":"tux.jpeg",
   "resourceId":"521afeb7d3a1d9ffef0f5c63",
   "socialId":null,
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"mobileTemplate",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

This operation allows for updating a specific file. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.resource.app.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): user account ID
• file (multipart request param): file attached

Request

POST /core.filestorage/resource/app/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: empty

This operation allows for deleting a specific file. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.resource.app.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): user account ID

Request

DELETE /core.filestorage/resource/app/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response: empty

This operation allows for assigning a custom social ID to a file. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.resource.app.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): resource file ID
• entityID: entity ID to set

Request

PUT /core.filestorage/updatesocial/{appId}/{resourceId}/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "name":"tux.jpeg",
   "resourceId":"521afeb7d3a1d9ffef0f5c63",
   "socialId":"12345",
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"mobileTemplate",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

This operation allows for reading a specified resource metadata. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.metadata.app.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/metadata/app/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
"name":"tux.jpeg",
   "resourceId":"521afeb7d3a1d9ffef0f5c63",
   "socialId":"12345",
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"mobileTemplate",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

This operation allows for reading all ap metadata entries. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.metadata.app.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• position: position to start from in the total list of metadata entries (default 0)
• size: number of entries to return (default 200)

Request

GET /core.filestorage/metadata/all/app/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

[
  {
  "name":"tux.jpeg",
     "resourceId":"521afeb7d3a1d9ffef0f5c63",
     "socialId":"12345",
     "fileExternalId":"tux.jpeg",
     "accountId":"521afe98d3a1d9ffef0f5c62",
     "appId":"mobileTemplate",
     "contentType":"application/octet-stream",
     "size":5315,
     "creationTs":1377500855280,
     "lastModifiedTs":0
  },
  ...
]  

This operation allows for reading a specified resource. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.resource.app.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/resource/app/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "metadata":null,
   "methodREST":"GET",
   "url":"https://dl.dropboxusercontent.com/1/view/wde60hkqsnyjd91/Apps/Smartcampuslab%20test/tux.jpeg",
   "httpHeaders":null,
   "storageType":"DROPBOX"
}

This operation allows for reading a specified resource shared with the user. The operation is performed with the app credentials, not with the user ones.

Permission

filestorage.sharedresource.app.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• userId (path variable): user ID
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/sharedresource/app/{appId}/{userId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {client access token}

Response

{
   "metadata":null,
   "methodREST":"GET",
   "url":"https://dl.dropboxusercontent.com/1/view/wde60hkqsnyjd91/Apps/Smartcampuslab%20test/tux.jpeg",
   "httpHeaders":null,
   "storageType":"DROPBOX"
}

This operation allows for uploading a file for the specified user account. The operation is performed with the user credentials.

Permission

filestorage.resource.user.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• accountId (path variable): user account ID
• file (multipart request param): file attached
• createSocialData: if the social entity should be automatically created and assigned to this file. Defaults to true

Request

POST /core.filestorage/resource/create/user/{appId}/{accountId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

?createSocialData=false

Response

{
   "name":"tux.jpeg",
   "resourceId":"521afeb7d3a1d9ffef0f5c63",
   "socialId":null,
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"mobileTemplate",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

This operation allows for updating a specific file. The operation is performed with the user credentials.

Permission

filestorage.resource.user.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID
• file (multipart request param): file attached

Request

POST /core.filestorage/resource/user/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response: empty

This operation allows for deleting a specific file. The operation is performed with the user credentials.

Permission

filestorage.resource.user.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

DELETE /core.filestorage/resource/user/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response: empty

This operation allows for reading a specified resource metadata. The operation is performed with the user credentials.

Permission

filestorage.metadata.user.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/metadata/user/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
"name":"tux.jpeg",
   "resourceId":"521afeb7d3a1d9ffef0f5c63",
   "socialId":"12345",
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"mobileTemplate",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

This operation allows for reading all the metadata entries of the user. The operation is performed with the user credentials.

Permission

filestorage.metadata.user.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• position: position to start from in the total list of metadata entries (default 0)
• size: number of entries to return (default 200)

Request

GET /core.filestorage/metadata/all/user/{appId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

[
  {
  "name":"tux.jpeg",
     "resourceId":"521afeb7d3a1d9ffef0f5c63",
     "socialId":"12345",
     "fileExternalId":"tux.jpeg",
     "accountId":"521afe98d3a1d9ffef0f5c62",
     "appId":"mobileTemplate",
     "contentType":"application/octet-stream",
     "size":5315,
     "creationTs":1377500855280,
     "lastModifiedTs":0
  },
  ...
]  

This operation allows for reading a specified resource. The operation is performed with the user credentials.

Permission

filestorage.resource.user.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/resource/user/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
   "metadata":null,
   "methodREST":"GET",
   "url":"https://dl.dropboxusercontent.com/1/view/wde60hkqsnyjd91/Apps/Smartcampuslab%20test/tux.jpeg",
   "httpHeaders":null,
   "storageType":"DROPBOX"
}

This operation allows for reading a specified resource shared with the user. The operation is performed with the user credentials.

Permission

filestorage.sharedresource.user.{appId}.read

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID

Request

GET /core.filestorage/sharedresource/user/{appId}/{resourceId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
   "metadata":null,
   "methodREST":"GET",
   "url":"https://dl.dropboxusercontent.com/1/view/wde60hkqsnyjd91/Apps/Smartcampuslab%20test/tux.jpeg",
   "httpHeaders":null,
   "storageType":"DROPBOX"
}

This operation allows for updating social information of a resource (entityId in specific). The operation is performed both with the user credentials and client credentials.

Permission

User credentials

filestorage.resource.user.{appId}.manage

Client credentials

filestorage.resource.app.{appId}.manage

Parameters:

• appId (path variable): application ID as registered in the developer console for this app
• resourceId (path variable): file resource ID
• entityID (path variable): social ID to bind to resource

Request

GET /core.filestorage/updatesocial/user/{appId}/{resourceId}/{entityId} HTTPS/1.1
Host: dev.smartcommunitylab.it
Accept: application/json
Authorization: Bearer {user access token}

Response

{
   "name":"tux.jpeg",
   "resourceId":"{resourceId}",
   "socialId": {entityID},
   "fileExternalId":"tux.jpeg",
   "accountId":"521afe98d3a1d9ffef0f5c62",
   "appId":"{appId}",
   "contentType":"application/octet-stream",
   "size":5315,
   "creationTs":1377500855280,
   "lastModifiedTs":0
}

The Filestorage Service client library provides an access to the operations exposed by the File Storage Service REST APIs.

The source code of the library is available at https://github.com/smartcampuslab/filestorage.client.

To use the library, one has to include the filestorage.client-2.0.jar and smartcampus.client.commons-2.0.jar into the project classpath. Also, the Jackson library for JSON parsing is required. In case of Android application, the library should be placed into the libs folder. When Maven is used to manage project libraries, one can use the following dependency:

	<dependency>
<groupId>eu.trentorise.smartcampus</groupId>
<artifactId>filestorage.client</artifactId>
<version>2.x</version>
<scope>jar</scope>
	</dependency>

Note that the SmartCommunity repository should be included in Maven configuration, e.g.:

	<repository>
<id>SmartCommunity</id>
<url>http://repository.smartcampuslab.it/content/groups/public</url>
	</repository>

The functionality is exposed by the Filestorage class. As of the REST API, almost all the methods are provided in two versions: from the user access and from the app

The primary goal of the library is to facilitate the access to the account management and the file management operations. Specifically, the library

• wraps the main file management operations and
• provide the implementation of the storage access authorization procedure.

1. Library download. If you are familiar with Git, the library may be checked out directly from the SmartCommunity GitHub repository here: https://github.com/smartcampuslab/android.remotefilestorage. Otherwise, the library is available as the part of the Android SDK here. Download and extract the SDK ZIP file. Note the location of the folder.

2. Import Library in Eclipse. The library folder is the Eclipse Android Library project itself. You can import this project into a workspace: go to Eclipse's 'File' > 'Import' menu, and select 'General' / 'Existing Projects into Workspace. If the projects are showing errors, simply use 'Project' > 'Clean' in Eclipse to refresh all the project's states.

3. Link the Filestorage library to your project. In your Android project you have to link to the library. To do this, view the properties for the project, and navigate to the 'Android' tab. In the lower part of the dialog, click 'Add' and choose the 'android.remotefilestorage' project from the workspace.

1. Set up .

First, ensure that your Android app has the 'android.permission.INTERNET' in the user permissions section:

<uses-permission android:name="android.permission.INTERNET" />

If the storage used by the app requires the user authorization (which is the case for the Dropbox storage, for instance) you have to register the authorization activity class:

<activity android:name="eu.trentorise.smartcampus.storage.AuthActivity"/>

2. AndroidFilestorage class.

The AndroidFilestorage extends the Filestorage class thus exposing all the method to operate the files and accounts via REST API calls. Additionally, it provides the method to deal with account authorization and creation

• isAuthenticationRequired: return true if the storage requires user authorization for access.
• createAccount: creates the user account out of the specified parameters.
• startAuthActivityForResult: initiates the authorization procedure for the user account creation.

3. User Account Management

The user account management includes the following steps.

First, it is necessary to check whether the account is already registered. The method should NOT be called from the UI thread. For example,

new AsyncTask<Void, Void, Account>(){
  @Override
  protected Account doInBackground(Void... params) {
    try {
      mFilestorage = new AndroidFilestorage("https://dev.smartcommunitylab.it/core.filestorage", "storage");
      Account account = mFilestorage.getAccountByUser(token);
      return account;
    } catch (Exception e) {
      // handle errors 
      return null;
    }
  }
 
  protected void onPostExecute(Account res) {
    // manage account, e.g., keep the account info somewhere
  }
}.execute();

If the account does not exist yet, and the authorization is not required, the new account can be immediately created:

new AsyncTask<Void, Void, Account>(){
  @Override
  protected Account doInBackground(Void... params) {
    try {
      mFilestorage = new AndroidFilestorage("https://dev.smartcommunitylab.it/core.filestorage", "storage");
      Account account = mFilestorage.createAccount(token, "storage", "name", StorageType.DROPBOX, configurations);
      return account;
    } catch (Exception e) {
      // handle errors 
      return null;
    }
  }
 
  protected void onPostExecute(Account res) {
    // manage account, e.g., keep the account info somewhere
  }
}.execute();

If the storage does not exist, and the authorization is required, the procedure is more complex. First, you have to start the authorization activity as follows:

try {
  mFilestorage.startAuthActivityForResult(MyActivity.this, res.toString(), StorageType.DROPBOX, 100);
} catch (Exception e) {
  // handle errors
}

This will start the authorization activity, which, upon completion returns the result to the calling activity. Therefore, it is necessary to handle the activity result:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  // user account acquisition complete
  if (requestCode == 100) {
    // user account acquired
    if (resultCode == Activity.RESULT_OK) {
      String accountId = data.getStringExtra(AndroidFilestorage.EXTRA_OUTPUT_ACCOUNT_ID);
      // account created, keep the accountID for the future uses
 
    // user account cancelled
    } else if (resultCode == Activity.RESULT_CANCELED) {
      // handle cancellation
    // user account failed
    } else {
      // handle failure
    }
  }
  ...
}  

4. File operation

Similarly to the client library, it is now possible to perform the file storage operations. Note that all the network operations should NOT be executed on the UI thread. For example,

new AsyncTask<Bitmap, Void, Bitmap> {
 
  protected Bitmap doInBackground(Bitmap... params) {
    try {
      Bitmap image = params[0];
      ByteArrayOutputStream byteArrayBitmapStream = new ByteArrayOutputStream();
      image.compress(Bitmap.CompressFormat.JPEG, 100, byteArrayBitmapStream);
 
      // ensure token is not expired 
      String token = mAccessProvider.readToken(MyActivity.this, Constants.CLIENT_ID, Constants.CLIENT_SECRET);
      // store file remotely
      Metadata metadata = mFilestorage.storeResourceByUser(						   
         byteArrayBitmapStream.toByteArray(),
         "image" + System.currentTimeMillis() + ".jpg",
         "image/jpg", token, mAccountId, false);
 
      if (metadata != null) {
         // read file remotely
         Resource resource = mFilestorage.getResourceByUser(token, metadata.getResourceId());
         if (resource == null) return null;
         byte[] content = resource.getContent();
          Bitmap bmp = BitmapFactory.decodeByteArray(content, 0, content.length);
          return bmp;
      } else return null;
    } catch (Exception e) {
      e.printStackTrace();
      return null;
    }
  }
 
  @Override
  protected void onPostExecute(Bitmap result) {
    // image read correctly
    if (result != null) {
      ImageView iv = (ImageView) findViewById(R.id.photo_iv);
      iv.setImageBitmap(result);
    } else {
      Toast.makeText(FileActivity.this, "Failed storing resource!", Toast.LENGTH_LONG).show();
    }
  }
}.execute(myBitmap);

~~DISQUS~~