The My Cloud Home SDK provides all necessary tools for you to quickly build apps and integrate them into the My Cloud Home platform. The SDK includes complete API documentation, sample codes, and client libraries.
The My Cloud Home APIs allow you to create, update, download and upload files. These APIs also include several advanced features like search, optimized thumbnails, sharing, optimized streaming and much more. The My Cloud Home APIs are built as ReSTful APIs. All information passed across APIs are in JSON format. All endpoints accept payload is in JSON format in the request body and return results in JSON format in the response body. All the APIs must use HTTPS protocol while making requests to My Cloud Home device or apps.
Please read the topics in the What is My Cloud Home section to get more information on My Cloud Home device and the application types, before proceeding to create your app.
The sections below will guide you to build your My Cloud Home app using APIs with step-by-step instructions.
Before you start using My Cloud Home API, you need to 1) register for a free Developer Portal account and 2) register your app. You will receive your app developer credentials (Unique Client ID/Secret code) for your application.
On receiving your credentials, you can follow this end-to-end development scenario to create your app.
Apps primarily talk directly to the My Cloud Home device to access content. However, applications need to talk to My Cloud Home cloud services for authentication, sharing, device lookup, etc.
My Cloud Home application requires calling config endpoint (config.mycloud.com/config/v1/config) to retrieve all service endpoints. For example, whenever an application wants to connect to the My Cloud Home Device, the device service endpoints will give the routing information to reach the device. The API documentation would provide information on which service endpoints to use for each API.
My Cloud Home configuration API returns the current configuration URLs for the My Cloud Home services. My Cloud Home recommends applications to use the configuration API before using any API.
Refer to the Get Configuration page for details on using the Configuration API.
Applications should check cloud endpoints periodically to get updated device endpoint, as it changes based on device location and other external factors like the network.
Endpoint
GET config.mycloud.com/config/v1/config
Response
Upon success, My Cloud Home Server returns a 200 status and provides the requested information in the response body. The response will return few endpoints that your application can use for future calls. Keep the key endpoints like "service.auth0.url" and "service.device.url" for future reference.
Example
GET /config/v1/config HTTP/1.1 Host: config.mycloud.com 200 OK { "error": null, "data": { "configurationId": "global_default", "name": "default", "modelId": "0", "modifiedOn": 1469574008000, "createdOn": 1469574008000, "componentMap": { "cloud.service.urls": { "service.device.url": "https://device.mycloud.com", "service.share.url": "https://prod-portal.mycloud.com", "service.auth0.url": "https://wdc.auth0.com", "service.client.url": "https://client.mycloud.com" } } } }
My Cloud Home uses OAuth 2.0 for authentication. All APIs should carry an authorization token, which is a credential that identifies the user and application to the My Cloud Home system. Apps must provide access token through an HTTP header. The Bearer token included in the Authorization header identifies the user and his/her permissions to access the content.
Authorization: Bearer <id_token>
The application must use the “service.auth0.url” endpoint retrieved in Endpoint Lookup for making authentication API calls.
Refer to the Authentication page for details on getting access token.
Tokens issued by My Cloud Home OAuth server are valid for a predefined time. You can ask for 'offline_access' scope and obtain a 'refresh_token' while doing the initial OAuth flow. The application can save the refresh token and request tokens using the saved 'refresh_token' when the token expires.
Device Lookup refers to finding the My Cloud Home device attached to the user’s My Cloud Home account. In a typical flow, a user signs-in to https://home.mycloud.com/ and looks for an associated My Cloud Home device. When the device is located, the direct route to the device can be obtained. All the file management API actions are made directly to the device.
Using access token retrieved in the above step, you can use Device Lookup APIs to find information about the user’s My Cloud Home device. Refer to the Device Information page for details on APIs used for device lookup.
The device object contains the following device reachability routes (URLs):
The My Cloud Home Device SDK provides required APIs that you can use to manage the user’s content. These REST APIs allow you to perform the following functions:
Let us discuss each of these functions below:
The File Management APIs enable you to access and manage content on My Cloud Home devices. The My Cloud Home file management refers to the CURD (Create, Update, Read and Delete) operations of files and folders. The File Management APIs are broadly classified into the following sections:
Refer to the File Management page to get details of the APIs used for File Management.
File Sharing APIs allow users to share their files or folders with others. Currently, My Cloud Home supports link-based sharing mechanism. Sharing link is a convenient way to share files with anyone. The link includes the required authentication to read the file. Anyone who has the file link will get access to the shared files.
Refer to the File Sharing page to get details of APIs used for File Sharing.
Creating a shareable link is a two-step process.
Once the file permissions are set, you can share the link retrieved through the first step. Opening the shared link in the browser allows the recipient to access all the shared files. The recipient is NOT REQUIRED to be a My Cloud Home user.
Search is an important part of accessing My Cloud content, and My Cloud Home supports the following modes of search.
Refer to the File Search page to get details of APIs used for File Search.
To support media-rich and performant client applications, My Cloud Home supports media thumbnails in varying sizes. Thumbnails for Images and Videos are made from the content itself whereas an audio thumbnail is extracted from the audio metadata. By default, My Cloud Home will automatically create few thumbnails based on the image size. It will try to match the requesting size with the ones it has.
Refer to the File Thumbnail page to get details of APIs used for Media Thumbnails.
Click the buttons below to visit the My Cloud Home Off-Device Developer Home & Workflow pages
