github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/shortcuts.md (about)

     1  [Table of contents](README.md#table-of-contents)
     2  
     3  # Shortcuts
     4  
     5  A shortcut is a file in the VFS with a `.url` extension. It is served with the
     6  `application/internet-shortcut` mime-type. The stack provides a few routes to
     7  help manipulate them.
     8  
     9  ## POST /shortcuts
    10  
    11  This route can be used to create a shortcut. You can create a shortcut using
    12  the `POST /files/:dir-id` route, but the content must respect the `.url` file
    13  format. This route offers an easier way to do that.
    14  
    15  **Note:** a permission to create a file is required to use this route.
    16  
    17  ### Request
    18  
    19  ```http
    20  POST /shortcuts HTTP/1.1
    21  Host: alice.cozy.example
    22  Content-Type: application/vnd.api+json
    23  ```
    24  
    25  ```json
    26  {
    27    "data": {
    28      "type": "io.cozy.files.shortcuts",
    29      "attributes": {
    30        "name": "sunset.jpg.url",
    31        "dir_id": "629fb233be550a21174ac8e19f003e4a",
    32        "url": "https://alice-photos.cozy.example/#/photos/629fb233be550a21174ac8e19f0043af",
    33        "metadata": {
    34          "target": {
    35            "cozyMetadata": {
    36              "instance": "https://alice.cozy.example/"
    37            },
    38            "app": "photos",
    39            "_type": "io.cozy.files",
    40            "mime": "image/jpg"
    41          }
    42        }
    43      }
    44    }
    45  }
    46  ```
    47  
    48  ### Response
    49  
    50  ```http
    51  HTTP/1.1 201 Created
    52  Content-Type: application/vnd.api+json
    53  ```
    54  
    55  ```json
    56  {
    57    "_id": "629fb233be550a21174ac8e19f0043af",
    58    "_rev": "1-61c7804bdb4f9f8dae5a363cb9a30dd8",
    59    "type": "file",
    60    "name": "sunset.jpg.url",
    61    "dir_id": "629fb233be550a21174ac8e19f003e4a",
    62    "trashed": false,
    63    "md5sum": "vfEMDpJShs8QeIlsDmw9VA==",
    64    "created_at": "2020-02-10T20:38:04Z",
    65    "updated_at": "2020-02-10T20:38:04Z",
    66    "tags": [],
    67    "metadata": {
    68      "target": {
    69        "cozyMetadata": {
    70          "instance": "https://alice.cozy.example/"
    71        },
    72        "app": "photos",
    73        "_type": "io.cozy.files",
    74        "mime": "image/jpg"
    75      }
    76    },
    77    "size": 62,
    78    "executable": false,
    79    "class": "shortcut",
    80    "mime": "application/shortcut",
    81    "cozyMetadata": {
    82      "doctypeVersion": 1,
    83      "metadataVersion": 1,
    84      "createdAt": "2020-02-10T20:38:04Z",
    85      "createdOn": "https://bob.cozy.example/",
    86      "updatedAt": "2020-02-10T20:38:04Z",
    87      "uploadedAt": "2020-02-10T20:38:04Z",
    88      "uploadedOn": "https://bob.cozy.example/"
    89    }
    90  }
    91  ```
    92  
    93  ## GET /shortcuts/:id
    94  
    95  This route can be used to get information about a shortcut. A permission to
    96  read the file is required to use it. There are two variants, depending on the
    97  `Accept` header.
    98  
    99  ### Request (JSON variant)
   100  
   101  If the `Accept` header is `application/vnd.api+json` (or `application/json`),
   102  the information are returned in JSON-API format.
   103  
   104  ```http
   105  GET /shortcuts/629fb233be550a21174ac8e19f0043af HTTP/1.1
   106  Host: alice.cozy.example
   107  Accept: application/vnd.api+json
   108  ```
   109  
   110  ### Response (JSON variant)
   111  
   112  ```http
   113  HTTP/1.1 200 OK
   114  Content-Type: application/vnd.api+json
   115  ```
   116  
   117  ```json
   118  {
   119    "data": {
   120      "id": "629fb233be550a21174ac8e19f0043af",
   121      "type": "io.cozy.files.shortcuts",
   122      "attributes": {
   123        "name": "sunset.jpg.url",
   124        "dir_id": "629fb233be550a21174ac8e19f003e4a",
   125        "url": "https://alice-photos.cozy.example/#/photos/629fb233be550a21174ac8e19f0043af",
   126        "metadata": {
   127          "target": {
   128            "cozyMetadata": {
   129              "instance": "https://alice.cozy.example/"
   130            },
   131            "app": "photos",
   132            "_type": "io.cozy.files",
   133            "mime": "image/jpg"
   134          }
   135        }
   136      }
   137    }
   138  }
   139  ```
   140  
   141  ### Request (Redirection variant)
   142  
   143  ```http
   144  GET /shortcuts/629fb233be550a21174ac8e19f0043af HTTP/1.1
   145  Host: alice.cozy.example
   146  Accept: text/html
   147  ```
   148  
   149  ### Response (Redirection variant)
   150  
   151  ```http
   152  HTTP/1.1 303 See Other
   153  Location: https://alice-photos.cozy.example/#/photos/629fb233be550a21174ac8e19f0043af
   154  ```