REST API fixes and extensions

[oparoz]

From @oparoz on October 5, 2015 13:39

Goals: Remove verbs and provide additional functionalities

Note: A node can be a file or a folder

Config

• /api/config

List and metadata

• 🆕 /api/nodes/{id} Get metadata for the node identified by its ID
• 🆕 /api/path:/{path} Get metadata for the node identified by its path
• 🆕/api/nodes/{id}/children List of images for an album identified by its ID
• /api/files/list -> /api/path:/{path}:/children Same as above, but using a path instead of an ID

Download

• /api/files/download/{fileId} -> /api/nodes/{id}/content Downloads a single image or all images contained in the folder (as a zip). Not sure I want to implement the folder part...
• 🆕 /api/path:/{path}:/content Same as above, but using a path instead of an ID

Preview

• /api/thumbnails Streamed thumbnails
• /api/preview/{fileId}/{width}/{height} -> /api/nodes/{id}/preview/{transform} Preview of a files identified by its ID
• 🆕 /api/path:/{path}:/preview/{transform} Same as above, but using a path instead of an ID

Note: transform would contain comma separated parameters such as w_1920,h_1080
Note2: The preview endpoints may even disappear owncloud/gallery#404

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Copied from original issue: owncloud/gallery#408

[oparoz]

From @Henni on October 6, 2015 11:55

@oparoz why don't you use url parameters for width and height instead of {transform}
/api/nodes/{id}/preview?width=1920&height=1080

[oparoz]

@Henni The main reason is so that you can just type a URL and get a result. It can be useful in some situations.

[oparoz]

From @Henni on October 6, 2015 13:42

@oparoz I don't see the advantage over appending ?width=1920&height=1080
It's not a big deal, but I think it is cleaner as URL parameters, especially as the order is unimportant.

[oparoz]

I'm not a 100% set on that. I find it easier to read and I saw it in other cloud/image processing APIs, but I don't think there is a rule.

/api/nodes/{id}/preview/w_1920,h_1080,t_crop,b_000033

vs

/api/nodes/{id}/preview/?width=1920&height=1080&t=crop&b=000033

Given how the Appframework works, I would make my life easier by going for parameters.

[oparoz]

On a related note, the preview endpoints may even disappear in 9.0 This ticket tracks the removal of our custom preview endpoints once they're obsolete: #404

[oliverpool]

An API for the shared files would be also nice.

For the authentification:

• it can either be done by providing the share_id in every request
• or by adding an endpoint to get credentials after providing the share_id

The second option seems to be the best, because one can then simply use the other routes!

Public

• api/share/{id}/credentials