Best Practices

Contents

• Best Practices
  • Introduction
  • Authentication
    • Token Expiration
    • Device IDs
  • Retrieving File and Folder Metadata
    • fullview
    • metadata
    • search
    • thumbnails

Introduction

The following tips are designed to guide application developers in the best ways to take advantage of the Personal Cloud Storage APIs.

Authentication

Token Expiration

• Attention!
  • Access tokens expire after 9 hours.
  • Refresh tokens expire after 14 days.
    

If you use an SDK, the access token is automatically refreshed by the SDK. If you allow the refresh token to expire however, the user will have to re-authorize your application in order for your app to regain access. For mobile-only apps this might be the expected behavior. For some server-side apps that run autonomously however, the app may need to refresh tokens automatically before the 14-day period is up in order to maintain access.

It is important to test that your app handles an expired refresh tokens correctly. It is possible to simulate an expired refresh token without waiting 14 days. To do so, visit www.myverizon.com and log in. Go to Services and select My Cloud Media and Contacts, then Settings and Manage App Permissions. Click Remove next to your app to remove your access and refresh tokens.

Device IDs

• Attention!
  • Refresh tokens are single-use only.
  • Each instance of your app receives the same refresh token.

If your application allows the use of multiple devices or platforms with the same application ID, you must ensure that each device or platform receives its own refresh token. To do that, use a device ID as a differentiator during the authentication flow. The device IDs you choose should be unique and constant for each device or platform.

If you do not use the device ID as a differentiator during the authentication flow, and one device or platform uses the shared refresh token to obtain a new access token, the other devices’ or platforms’ refresh tokens will expire and they will not be able to refresh.

Device ID can also be necessary during application development, in cases where user IDs are shared between developers.

Retrieving File and Folder Metadata

There are three different methods that you can use to retrieve the metadata for files or folders. Each method has a different set of advantages and disadvantages described below.

fullview

GET /fullview API returns the metadata for all files and folders within a specified virtual folder.

• Advantages

  • You can use this end point repeatedly to poll for changes to the specified account, such as new, updated, or deleted files or folders.

• Disadvantages

  • The response is not paginated and cannot be filtered.
  • The metadata for all files and folders is always returned.
  • Can be quite slow for larger accounts. We recommend using it only in the background. We do not recomment using this endpoint when the end user is waiting for the response.

metadata

GET /metadata API returns the metadata for a single file or folder. For folders, it includes the metadata of the contents of the folder.

• Advantages

  • At the root level, you can use this endpoint to obtain a list of virtual folders, which is often the first step for retrieving the metadata information.
  • For folder requests, including child folders, responses are paginated and the response times are somewhat predictable.
  • Useful for apps where the UI is geared towards driving down into folders.

• Disadvantages

  • Filtering options are limited.
  • You cannot retrieve the metadata for files or folders outside of a specified folder.
  • Polling for changes is difficult. You can sort responses by modifiedDate parameter. This approach however, does not display information on deleted files or folders.

search

GET /search returns the metadata for a list of files or folders that match a specific query.

• Advantages

  • Responses are paginated and response times are somewhat predictable.
  • This is the only method that allows you to retrieve the metadata across multiple virtual folders.
  • A good approach if your app retreieves metadata only for specific file types, such as images or videos.

• Disadvantages

  • Polling for changes is difficult. You can sort responses by modifiedDate parameter. This approach however, does not display information on deleted files or folders.

thumbnails

You can specify the thumbnail size in two different ways:

• using th(thumbnail height) and tw(thumbnail width) parameters
• using the size parameter with possible values of xs, s, m, and l
  

What you should consider:

• Using th & tw parameters can be significantly slower than using the size parameter.
  
• The th & tw options are appropriate if you are requesting a single thumbnail.
• If you are requesting a pageful of thumbnails it is best to use size to specify a preconfigured thumbnail size.
• The maximum size of thumbnail should be 1080x1080 pixels or original image size, whichever is lower.

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.