Migrating from v0 to v1

Introduction 

v1 improves Kloudless’s support for new APIs, features as well as authentication mechanisms. Support for v0 will be removed on February 28, 2018.

This migration guide provides an overview of backwards incompatibilities that require changes to be made to your application when migrating from v0 to v1.

Here is a summary of the backwards-incompatible changes described below:

  • All endpoints specific to the Storage API have been name-spaced under /storage/.

  • OAuth 2.0 authentication is required. The previous authentication format is no longer supported.

  • OAuth 2.0 Bearer tokens have replaced Account Keys.

  • Deprecated event object attributes have been removed.

  • next_page must be used to identify the next page value for pagination.

  • Files are uploaded as binary content rather than via multipart form POST requests.

  • File/Folder permission updates take in a list of permission objects rather than a mapping of user emails to roles.

  • Event cursors are now strings instead of numbers.

API-namespacing for endpoints 

All endpoints compromising the Storage API will be namespaced within the /storage/ URL fragment. This provides flexibility with APIs for additional non-storage services.

Here are the endpoints that will be moved:

  • /v0/accounts/{account_id}/files/ -> /v1/accounts/{account_id}/storage/files/

  • /v0/accounts/{account_id}/folders/ -> /v1/accounts/{account_id}/storage/folders/

  • /v0/accounts/{account_id}/multipart/ -> /v1/accounts/{account_id}/storage/multipart/

  • /v0/accounts/{account_id}/links/ -> /v1/accounts/{account_id}/storage/links/

Endpoints that will remain the same, except for the version:

  • /v1/accounts/{account_id}/events/

  • /v1/accounts/{account_id}/team/

Endpoints that will no longer exist:

  • /v0/accounts/{account_id}/keys/ Account Keys have been replaced with OAuth 2.0 Bearer tokens that must always be stored and cannot be retrieved via the API.

OAuth 2.0 Authentication 

The previous authentication mechanism has been deprecated and must no longer be used. It is not supported in versions beyond v0. For the new authentication mechanism, check out our updated docs.

For reference, the older authentication mechanism is documented below.

Deprecated Authentication Mechanism

You can connect your users’ cloud storage accounts to the Kloudless platform by redirecting them to us. We will redirect them back to a callback URL you provide with their account ID and the cloud storage service they chose.

The URL to redirect a user to is of the form:

https://api.kloudless.com/services/?app_id=APP_ID&callback=CALLBACK&services=list,of,services&admin=

  • APP_ID: This is your Kloudless application’s App ID

  • CALLBACK: This is a url-encoded callback URL to send users back to your website after they have connected a cloud storage account. Query parameters will be added to the callback URL:

    • account: The ID of the Account that was connected.
    • service: The name of the service that was connected.
    • error_code: If there is an error, the error code.
    • message: If there is an error, the error message containing details of error.

  • services: Optional. This allows you to only display a subset of services for the user to be able to connect. If only one is provided, we will immediately redirect to it. The service names must be comma-separated, and must be from the list of currently supported services.

  • admin: Optional. Set to 1 to request admins to authorize access to their organization’s data. You can then list team members and perform API requests on behalf of them.

Here are some examples:

# Authenticate a user and redirect back to http://localhost:8080/callback
# An example URL redirected to is:
#   http://localhost:8080/callback?account=50&service=box
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback

# Only display Box and Dropbox
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback&services=box,dropbox

# Take the user directly to Dropbox to authenticate
https://api.kloudless.com/services/?app_id=APP_ID&callback=http%3A%2F%2Flocalhost%3A8080%2Fcallback&services=dropbox

Account Keys replaced with OAuth 2.0 Bearer tokens

Account Keys were previously available with the v0 authentication scheme. These were automatically created when a user connects an account to the application, and were used to authorize access to the account, especially from the client-side:

Authorization: AccountKey {account_key: string}

OAuth 2.0 Bearer Tokens have replaced Account Keys. Existing Account Keys can be migrated to Bearer tokens via this endpoint.

When using Account Keys, a request to multiple accounts can be authorized by comma-separating the necessary Account Keys. For example:

curl -L -H 'Authorization: AccountKey key_123,key_456,key_789' \
    https://api.kloudless.com/v0/accounts/123,456,789/links

For more information on creating and retrieving Account Keys, see the v0 Account Keys endpoint.

Events 

Properties of an event object that the v0 documentation warned would be removed in v1 have been removed. Here are the changes:

  • id: Now refers to the event ID rather than the ID of the object associated with the event. To obtain the ID of the object, see metadata.

  • Event IDs are now character strings rather than integers.

  • event_id: Removed. Use id instead.

  • action: Use type instead.

Pagination 

The v0 API’s endpoints’ pagination formats differed from one another. The v1 API moves to a consistent format for paginated data can be obtained.

Requests using the new format accept the following query parameters, unless otherwise specified:

  • page: A string identifying the ID of the page to retrieve. For the first page, use 1.

  • page_size: The number of objects to retrieve per page. This field may not be supported for all endpoints since the page size might not be modifiable once pages beyond the first page have been retrieved.

Responses using the new format provide the following attributes, unless otherwise specified:

  • page: A string identifying the ID of the current page.

  • next_page: A string identifying the ID of the next page. null if no further pages are available.

  • count: The number of objects in the current page.

  • objects: The list of objects.

See each endpoint for further details. Endpoints that deprecate previous pagination formats include:

  • Retrieving Folder Contents has_next removed.

File Uploads 

Previously, File Uploads used multipart POST requests to transfer data. Since this proved unnecessarily complex, it has been replaced with binary file uploads.

The older version remains documented below for reference.

Deprecated File Upload endpoint 

Upload a FilePOST /accounts/{account_id}/files/{?overwrite}

To upload a file, perform a multipart POST request with the metadata part containing a JSON string with attributes:

  • parent_id: The ID of the Folder to upload the file to.

  • name: The name of the file being uploaded.

Here is an example:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v0/accounts/123/files' \
    -F metadata='{"parent_id": "fL2hp", "name": "test.png"}' \
    -F file=@FILENAME
  • Parameters
  • overwrite
    boolean (optional) Default: False 

    Specifies whether to overwrite existing files

    Choices: False True

  • RequestToggle

  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: multipart/form-data; boundary=----------------------------af064662d035

    Body

    ------------------------------af064662d035
Content-Disposition: form-data; name="metadata"

{"parent_id": "fL2hp", "name": "test.png"}
------------------------------af064662d035
Content-Disposition: form-datal name="file"; filename="FILENAME"
Content-Type: image/png

[file contents]
------------------------------af064662d035--

Raw Data 

The format of raw data received in API responses from an upstream third-party service has changed. In v0, raw data was included in the raw attribute’s object. In v1, raw data will be nested within an object attribute in the raw object, unless otherwise specified.

For example, here is the format in v0:

{
        "raw": { ... raw data ... }
    }

Here is the equivalent format in v1:

{
        "raw": {
            "object": {raw_data_dictionary}
        }
    }

Permissions 

Previously, Permissions updates required a mapping of user emails to roles. This has been updated to accept a list of objects instead, similar to the Properties endpoint.

The older version remains documented below for reference.

Set permissions 

Set permissionsPUT /accounts/{account_id}/{files,folders}/{file_id,folder_id}/permissions

To set permissions on a resource, create a JSON object with each key as an email and value as the role to assign. All permissions for the resource must be specified. Any existing permissions on the resource will be overwritten.

If you would prefer to only alter a subset of permissions, check out the PATCH endpoint instead.

The JSON object in the request consists of:

  • email The email of the user you’re setting permissions for

  • role The user’s role, as described in Permissions.

    • If you specify an empty string "" it will remove any permissions belonging to this user

If you PUT an empty JSON object {}, it will remove all permissions for this resource.

For example:

{
        "reader@test.com": "reader",
        "writer@test.com": "writer",
        "previewer@test.com": ""
    }

The response contains permission information in the same format as returned by the list endpoint.

Example request:

curl -X PUT -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"writer@test.com": "writer", "reader@test.com": ""}'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle

  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
  "writer@test.com": "writer",
  "reader@test.com": ""
}
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "permissions": [
    {
      "id": 54288134,
      "email": "writer@test.com",
      "name": "Test Writer",
      "role": "writer"
    }
  ]
}

Update permissions 

Update permissionsPATCH /accounts/{account_id}/{files,folders}/{file_id,folder_id}/permissions

To update permissions on a resource, create a JSON object with the user’s email set to the appropriate role. See the PUT endpoint for more information on the request and response format.

Example request:

curl -XPATCH -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -d '{"writer@test.com": "writer", "reader@test.com": "", "previewer@test.com": "previewer"}'
    'https://api.kloudless.com/v0/accounts/12/files/fZGVycGRlcnBkZXJwCg==/permissions'
  • RequestToggle

  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
  "writer@test.com": "writer",
  "reader@test.com": "",
  "previewer@test.com": "previewer"
}
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "permissions": [
    {
      "id": 54288134,
      "email": "writer@test.com",
      "name": "Test Writer",
      "role": "writer"
    },
    {
      "id": 211581041,
      "email": "previewer@test.com",
      "name": "Test Previewer",
      "role": "previewer"
    }
  ]
}

Events API cursor data type 

The cursor provided in the response to requests to the Activity API can now be a string instead of only a number.