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.
Sign up for a Developer Account
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.
Step 1: Endpoint Lookup
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.
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.
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.
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.
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.
Step 3: Device Lookup
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):
internalURI is the device endpoint that can be used when the application is on the same network as the My Cloud Home device. For example, at home.
externalURI is the device endpoint that can be used when the application is not on the same network as the My Cloud Home device. For example, in the office or in the park.
Step 4: Manage Content
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:
File/Folder Creation – API to create Files and folders in My Cloud Home device.
File/Folder Navigation – API to navigate between folders.
File Metadata – API to retrieve file metadata.
File Upload/Download – APIs to upload/download file content.
File Operations – API to make file operations like rename, move and delete.
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.
Create a sharable link using POST call /v1/shares for the selected file or folder IDs. This will return the "url" and "authId".
Make a new POST call /sdk/v1/filePerms to the My Cloud Home device to set read-only permissions for the selected file or folder with the retrieved "authId".
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.
Search files by text
Search a file in a folder
Search for media files by time
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.