telabotanica / cumulus Goto Github PK

Example :
http://api.tela-botanica.org/service:cumulus:doc/_projets/1

URLs representing a path, like /my/folder, should return the whole content available under this path.
For example something like:

{
  folders: [
    ...
  ],
  files: [
    ...
  ]
}

It could accept ?R switch (recursive).

Currently, calling GET on / will display usage info and it is impossible to obtain the / folder contents.
Maybe move usage to /api/ ? The risk is having many users call / and consume a lot of resources to obtain something they don't want.

Routes such as /by-path or /search don't represent a resource but a service, ans as such are not really REST-compliant.
To avoid collision with resources, prefix all service routes with /api (for ex.).
The only remaining drawback will be : impossible to create a file / folder named "api" at the storage root.

Using /api/search entry point with an unknown parameter gives an unexpected result.

http://domain.com/cumulus/api/search?foobar=stuff

=>

{
    "count": 1,
    "results": false
}

Should be :

{
    "count": 0,
    "results": []
}

For ex: calling http://mydomain.tld/cumulus/api/by-path/ might return no results. In such a case, it returns 404 although the URL is valid. It should return 200.

Note: is it OK to return a JSON "error" object (currently { "error": "no results" }, or should we return an empty list ?

Depending on the command called, the trailing slash is either mandatory or fatal !

http://api.tela-botanica.org/service:cumulus:doc/api/by-path/_projets/1?R => works :)
http://api.tela-botanica.org/service:cumulus:doc/api/by-path/_projets/1/?R => ignores recursivity :(

http://api.tela-botanica.org/service:cumulus:doc/api/by-path/_projets/1/ => works :)
http://api.tela-botanica.org/service:cumulus:doc/api/by-path/_projets/1 => doesn't :(

Each file could have a list of users (email addresses) it is shared with. Each item could be a couple email address / permission (read or write).

Either truncate file name or report specific error:

<br />
<b>Warning</b>:  mkdir(): File name too long in <b>/var/www/back/adapters/storage/stockagetb/StockageDisque.php</b> on line <b>123</b><br />
{"error":"disk storage: cannot create directory"}

For exemple, call a URL or send a notification when a new document is uploaded.

This could also be achieved using an event publication system (à la pump.io).

Unless #18 is implemented, elements of $this->resources should be array_shift()ed each time one is examined, so that an element is never used twice.

Especially when last elements are examined like /dl, they might conflict : what if a file has the dl keyword ?

/by-path/foo/?R returns /foo/* but also /foobar/, /foobaz/ etc.
The recursivity should crawl down the "foo" folder, but sould not include "foo*" folders (add a "/" somewhere in the regex).

A fulltext indexer (like Lucene) could index files and keep track of their Cumulus key. Additionnaly, CumulusService could propose a /fulltext entry point and / or a "fulltext" parameter for /search entrypoint.

Like in this response:

<br />
<b>Warning</b>:  mkdir(): File name too long in <b>/var/www/back/adapters/storage/stockagetb/StockageDisque.php</b> on line <b>123</b><br />
{"error":"disk storage: cannot create directory"}

A new service entry point could return all the "folders" directly (or indirectly, with ?R parameter) under a path. Such a "folder" would be defined as any path element containing at least one file or sub-"folder", and starting with the path given as argument.

Examples :
GET http://domain.tld/cumulus/get-folders/root/path
GET http://domain.tld/cumulus/get-folders/root/path?R

Other possibility : return the folders along with the files, for any "by-path" query (makes navigation easier)

It's up to each AuthAdapter to choose how to represent a user; AuthTB should use the user ID instead of the email address, to preserve privacy.

Improve the unit test example URIs given in config/service.default.json to build a real testing set.