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

[Val]

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. 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.

[Val]

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

[Val]

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.