Improve OCS Share API documentation

[marcos-guerrero]

Hello!
I'm opening this issue here, as the same was closed in the server repository: nextcloud/server#7350

==================================================================
I'm trying to issue the requests through my own client (POSTMAN) and comparing with the requests sent by the browser when I create / update a link on the web interface... and It's hard to understand the differences in terms of the POST (create) and PUT (update) requests between
A) "Share with other people by entering a user or group or an email address" (I'm currently using an email address)
B)"Share link"

option A) uses share_type = 4 (not documented) and B) uses share_type = 3.
Besides, giving both options the same permissions "file drop (upload only)" I see permissions = 14 in option A) and permissions = 4 in option B). The parameters in the requests are reflected on the oc_share table:

+----+------------+-----------------------------+-----------+---------------+--------+-----------+-------------+-------------+-------------+-------------+-------------+------------+----------+------------+-----------------+-----------+------------+----------+
| id | share_type | share_with | uid_owner | uid_initiator | parent | item_type | item_source | item_target | file_source | file_target | permissions | stime | accepted | expiration | token | mail_send | share_name | password |
+----+------------+-----------------------------+-----------+---------------+--------+-----------+-------------+-------------+-------------+-------------+-------------+------------+----------+------------+-----------------+-----------+------------+----------+
| 9 | 3 | NULL | data_user | data_user | NULL | folder | 45 | NULL | 45 | /Photos | 4 | 1512030198 | 0 | NULL | O0qzkaDIH2Aup1o | 0 | NULL | NULL |
| 12 | 4 | marcos.guerrero@xxxxx.com | data_user | data_user | NULL | folder | 45 | NULL | 45 | | 14 | 1512041789 | 0 | NULL | wnYI6rjXkPYl7Mc | 0 | NULL | NULL |
+----+------------+-----------------------------+-----------+---------------+--------+-----------+-------------+-------------+-------------+-------------+-------------+------------+----------+------------+-----------------+-----------+------------+----------+

So, how could I learn about share_type = 4 ? And what about permissions = 4 and 14 giving the same kind of link (file drop link) ?

And after that, there are more doubts / undocument behaviour in share_type 4 that makes it completely different of share_type 3 , by trial and error I suppose that on create (POST) it doesn't matter which parameters you send, and password, expireDate, permissions are only set on next calls to PUT ... But it's only my trials... But my service of public links based on nextcloud could benefit a lot if I were able to know how to manage share_type 4 links

Thank you very much in advance for your attention and help

[diegosps]

Hello. Did you figure it out?
Also, could you share some examples on the sharing api? I'm struggling with it.
I managed the file handling pointing the the webDAV endpoint as a network drive in windows. Then I could handle it like a file system.
Thank you.

[MorrisJobke]

cc @nextcloud/sharing