REST API fixes and extensions

[oparoz]

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 #404

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

[Henni]

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

[Henni]

@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

[oparoz]

This issue was moved to nextcloud/gallery#95