+ Reply to Thread
Results 1 to 3 of 3

Thread: API 2.1-28 (Release Date: 2014-04-15) "directory sharing"

  1. #1

    API 2.1-28 (Release Date: 2014-04-15) "directory sharing"

    summary
    With this release a major new funcionality is introduced to the API. The so called "sharedir" feature (/share), which allows any user to share any directory inside his HiDrive. Furthermore the BUG #1684 (CORS support) has been fixed.

    /2.1/... changes
    Type Endpoint Description
    Feature * /2.1/share Set of new endpoints to manage the newly introduces directory sharing feature. Create/Edit/List/Delete shares.
    Notice: as of now, this endpoint only manages directory shares (sharedirs), which are following a new concept (see details below)
    Feature POST /2.1/share/token Public endpoint to retrieve an access_token for a given share-id (and optional password). If you want to create a sharedir interface, or access any data from sharedirs, you need to use this endpoint. (see details below)
    Feature DELETE /2.1/share/token New endpoint to revoke a share access_token.
    Improvement * /2.0/dir
    * /2.0/file
    * /2.0/file/archive
    * /2.0/file/image
    * /2.0/fs
    * /2.0/mailupload
    * /2.0/meta
    * /2.0/sharelink
    * /2.0/shareupload
    * /2.0/share
    Parameter 'path' may now be shortened to '/...'. E.g.
    Code:
        path='/' == path='root'
        path='/public' == path='root/public'
        path='/users/foobar' == path='root/users/foobar'
    The returned path answer
    (Future major versions of the API are likely to require paths to be given in a shortened way)
    Improvement all endpoints Endpoints now have additional "capability" checks. The API-Reference "Method Documentation" was extended accordingly. (see details below)
    Bugfix OPTIONS /2.1/* ALL API endpoints now answer to valid CORS OPTIONS requests in the way http://www.w3.org/TR/2014/REC-cors-20140116 describes it.
    Last edited by Val; 2014-04-15 at 03:01 PM.

  2. #2
    SHAREDIR details

    The new directory sharing feature is intended to allow HiDrive users to grant public (or password protected) access to specific directories. An app may do both, support the management of shares for HiDrive users and utilize access to existing shares of other users.

    To allow share management:
    Read the documentation for the newly created GET/POST/PUT/DELETE /2.1/share endpoints. The options and Usage is quite simmilar to existing sharing options (/2.1/sharelink, /2.1/shareupload, /2.1/mailupload). And yes, those are a lot of endpoints for fairly simmilar operations, we are aware and thinking about potential ways to improve the interface in the future.

    To utilize shares:
    Besides our own web interface, everybody is able to create own software to read and use shares. The POST /2.1/share/token Endpoint allows everyone to get a restricted OAuth2 access_token for a given share id.
    This access_token may then be used to call regular API endpoints, simmilar to regular API usage. However, there are a few differences and limitations:
    User access_token Share access_token
    Read/Write (if granted by user) Read-Only
    "path=/..." leads to HiDrive ROOT ("root/...") "path=/..." leads to shared dir ("root/users/foobar/my/sharedir/...)
    Anonymous share access does not expose information about the location of a share inside HiDrive!
    1h lifetime 4h lifetime
    all endpoints available only "Filesystem Access" endpoints available
    Last edited by Val; 2014-04-10 at 05:03 PM.

  3. #3
    PERMISSION details
    In order to limit access from sharedir token to specific endpoints, we implemented a basic group based system for permissions.
    There are 3 types of permissions an endpoint can require:

    • Filesystem Access (fs) - Everything related to accessing data on the HiDrive
    • Sharing (share) - Endpoints required to share data frim HiDrive
    • HiDrive Management (mgmt) - General account and quota management endpoints


    Those permissions affect the endpoints accessible in general, as well as the available "fields" parameters inside accessible endpoints. For example "Filesystem Access" grants you the permission to use GET /2.1/dir BUT you won't get information for "fields=share,rshare,..." since share based Information requires "Sharing" permission.
    This ensures that share access_token might read the shared files, but can't read sharelink-data etc. for files.

    The documentation inside the API-Reference has been updated to provide information about the permission requirements of endpoints. The former "PERMISSION" section allowing the values "Public, User, Administrator, Owner" has been renamed to a more suitable "AUTH ROLE".
    "PERMISSION" now states which of the 3 listed permissions are required from an app.

    "Public" endpoints do not have Permission restrictions for obvious reasons.

    Existing regular apps have all 3 Permissions for the time being, whereas share access_token only have "Filesystem Access" permission.
    We keep you updated if and when this might be extended or changed.
    Last edited by Val; 2014-04-10 at 04:58 PM.

+ Reply to Thread

Posting Permissions

  • You may not post new threads
  • You may post replies
  • You may not post attachments
  • You may edit your posts
  •