diff --git a/docs/ocis/adr/0011-global-url-format.md b/docs/ocis/adr/0011-global-url-format.md index ce46f322367..0161c407ced 100644 --- a/docs/ocis/adr/0011-global-url-format.md +++ b/docs/ocis/adr/0011-global-url-format.md @@ -318,3 +318,60 @@ Public links would have the same format: `https:///files?id=` {{< hint warning >}} Since there is no difference between public and private files a logged in user cannot see the public version of a link unless he logs out. {{< /hint >}} + + +## CERN Proposal for cleaner and user friendly URLs + +We believe that URLs exposed in the browser address are a critical area to be properly maintained and evolved. Changes to bookmarked URLs can and will break user behaviour. +We think that the current URLs exposed in the recent changes in Web can be improved and we propose some changes for discussion. +We have also realized that this ADR is outdated and does not reflect the current URLs used in the Web: spaces are not taken into account. + +The way this section is written is to start a discussion to formulate better URLs and make a more formalised proposal to this document. + +We propose you to take a look at the following examples and the inner motivations for improvement: + +### Examples + +| Current | Proposed | +|---------|----------| +| https://cernbox.cern.ch/files/spaces/personal/home/eos/user/d/dalvesde?items-per-page=100&sort-by=name&sort-dir=asc | https://cernbox.cern.ch/files/spaces/eos/user/d/dalvesde?items-per-page=100&sort-by=name&sort-dir=asc | +| https://cernbox.cern.ch/draw-io/files-spaces-personal-home/files/dalvesde/eos/user/d/dalvesde/cbox%20transition.drawio?contextRouteParams.storage=home&contextRouteParams.item=/eos/user/d/dalvesde | https://cernbox.cern.ch/draw-io/spaces/eos/user/d/dalvesde/cbox%20transition.drawio?previous=/files/spaces/eos/user/d/dalvesde | +| https://cernbox.cern.ch/external/files-spaces-personal-home/eoshome-d!1377773/Microsoft%20Office?contextRouteParams.storage=home&contextRouteParams.item=%2Feos%2Fuser%2Fd%2Fdalvesde | https://cernbox.cern.ch/external/spaces/eos/user/d/dalvesde/New%20file.docx?app=microsoft-office&previous=/files/spaces/eos/user/d/dalvesde | +| https://cernbox.cern.ch/files/public/show/sstLvrDFEpxwwxL?items-per-page=100 | https://cernbox.cern.ch/files/public/sstLvrDFEpxwwxL?items-per-page=100 ?? (do we need `show`?) | +| https://cernbox.cern.ch/external/files-public-files/eoshome-d!2639/Microsoft%20Office?contextRouteParams.item=sstLvrDFEpxwwxL&public-token=sstLvrDFEpxwwxL | https://cernbox.cern.ch/external/public/sstLvrDFEpxwwxL/New%20file.docx?app=microsoft-office&previous=/files/public/sstLvrDFEpxwwxL | + + +* We strip off `personal/home` as it does not bring any value to the URL and makes the URL relative to the current user, making it impossible to just copy and paste the URL to be reused by another user. +* The files app works with slashes (files/spaces/personal/home/) and the application works with dashes (files-spaces-personal-home). We find no sense to this distinction. +Applications should not behave differently that the files app (another application). +* We find the usage of query parameters `contextRouteParams.*` confusing and we prefer to opt for a more natural value (the previous url) with the `previous` query parameter. Note that this query parameter should only be used for applications rendered inside the Web (not for external applications opening in a tab). + +### Preserving the possibility to copy and paste URLs based on paths + +We would like to register `eos` as a space alias, so that we can continue providing the nominal file path: `https:///files/spaces/eos/user///`. +The usage of UUIDs is not user friendly and does not bring semantic meaning for the user. + + +### Application URLs + +Applications are a key technology enables for users and we want users to be fully engaged in a rich experience by using a vast array of applications inside the OCIS platform, not limiting the usage to just uploading and downloading files. Therefore, we believe application URLs should be a fundamental design choice alongside the files application routes, providing (and enforcing) application developers to follow guidelines for url routing. + +In general, urls should be of the type: + +* `/` or +* `/public/` for public links (allowing to distinguish if they need to be authenticated or not) + +Example: `https:///draw-io/spaces/eos/user/d/dalvesde/CERNBox/cbox transition.drawio` + +This would preserve the exact same schema used in the files app (just the app name changes). In order to know where to return on close, just add a `previous` query parameter with the previous route. + +We would also recommend that the previous route is ommited from applications opened in a new tab, as closing the tab should be the recommended way of getting back to the previously opened files. + +#### Special case: external app +This application acts as bridge to other (external) applications, hence the name. + +Two options: + +* `/external//full/path/to/doc` (where app-name can be "default") +* `/external/full/path/to/doc?app=` (where ommiting the app name opens the default) +