# This specification is "Work in progress" and is not yet finished.

## File link resources

`FileLink` resources in OpenProject describe links between resources in OpenProject (first work packages, maybe in the future wiki pages, etc.) and their representation in a file store, i.e. a file in Nextcloud or in a Google Drive.

Begin of the insertionA `FileLink` consists of roughly three types of attributes

* first class citizens such as
* the link's ID (not the file's ID)
* the storage ID within OpenProject (That becomes handy once we want to allow for multiple storages)
* origin data which are attributes of the linked file
* the files ID in external file storage, such as Nextcloud's `fileId`.
* the file name
* the file's mime type
* the name of the files author who created the file
* the name of the person who last updated the file
* links to other, mostly OpenProject resources
* The user/author who created the link
* The container to which the file is linked to, i.e. a certain work package. In future it could be also something else such as wiki pages etc.
* The path for deletion
* Links for downloading the file
* One that is the download location from the origin
* Another that is redirecting to the one above but is relative to OpenProject's root (in case the one above changes for whatever reason)
* A link for opening the file in the origin's web app, i.e. open the a .docx in the Nextcloud online editor
* Maybe we even need a link to show the file in the origin's web app's file structure

End of the insertion ## GET all file links to work packages of project a project from a certain file store

Example: _"Get all file links linking to work packages in project 5 that are stored in file store 1"_

For readability reasons we chose to show the URL params not URL encoded in this example. The params must be URL encoded first if you want to use them in a real example.

`GET /api/v3/file_links?filters=[{"resource_type":{"operator":"=","values":["WorkPackage"]}},{"project_id":{"operator":"=","values":["5"]}},{"file_store":{"operator":"=","values":["1"]}}]`

This will return a collection of file reference resources.

```json
{
"_type" : "collection",
"count" : 2,
"total" : 2,
"_embedded" : {
"elements" : [
{
"id" : 1,
"storageType" : "nextcloud",
"storageId" : 1,
Begin of the insertion"createdAt" : "2021-12-20T14:01:45Z",
"updatedAt" : 2021-12-20T15:12:01Z",
End of the insertion "originData" : {
"id" : 5502
"createdAt" : "2021-12-20T13:37:45Z",
"lastModifiedAt" : "2021-12-20T14:27:01Z",
"authorName" : "Manuel Müller",
"lastModifiedByName" : "Christina Bolz",
"fileName" : "picture_1.png",
"mimeType" : "image/png",
},
"_links" : {
"self" : {
"href" : "/api/v3/file_links/1",
"title" : "picture_1.png"
},
"downloadLocation" : "https://mynextcloud.com/..."
"staticDownloadLocation" : "/api/v3/file_links/1/download",
Begin of the insertion"originOpen"End of the insertion Begin of the deletion "origin"End of the deletion : "https://mynextcloud.com/index.php/apps/files/?fileid=5502",
Begin of the insertion"originShowLocation" : "https://mynextcloud.com/index.php/apps/files/?fileid=5502",
End of the insertion "author" : {
"href" : "/api/v3/users/3145",
"title" : "Richard Wolf",
},
"delete" : {
"href" : "/api/v3/file_links/1",
"method" : "delete"
},
"container" : {
"href" : "/api/v3/work_packages/22",
"title" : "Awesome work package with file references"
}

},
"_type" : "FileLink"
},
{
...another file link
}
]
}

},
```

## GET work packages that are related to Begin of the insertionfile's origin IDEnd of the insertion Begin of the deletion file linkEnd of the deletion

To query all work packages that are linked to a file you need to apply the filter Begin of the insertion`origin_id` and `file_store`End of the insertion Begin of the deletion `originId`End of the deletion to the `work_packages` API endpoint.  This filter allows only one operator `=` and multiple IDs as values, for example in case of a Nextcloud storage the IDs are Nextclouds `fileid`s.

Example: _"Get all work packages that are linked to two certain files with their original IDs being 1234 and Begin of the insertion1235 and the storage ID 1."_End of the insertion Begin of the deletion 1235."_End of the deletion

Attention: For readability reasons we chose to show the URL params not URL encoded in this example. The params must be URL encoded first if you want to use them in a real example.

`GET Begin of the insertion/api/v3/work_packages?filters=[{"origin_id":{"operator":"=","values":["1234","1235"]}},{"file_store":{"operator":"=","values":["1"]}}]`End of the insertion Begin of the deletion /api/v3/work_packages?filters=[{"originId":{"operator":"=","values":["1234","1235"]}}]`End of the deletion

This will return a collection of work package resources.

## **GET file links that are related to a work package**

For displaying all links to all files next to a work package, for example in a "Nextcloud" tab of a work package, we need to be able to query all file links linking to a work package.

Example: _"Get me all files that are linked to work package 1."_

For readability reasons we chose to show the URL params not URL encoded in this example. The params must be URL encoded first if you want to use them in a real example.

`GET /api/v3/file_links?filters=[{"container_type":{"operator":"=","values":["WorkPackage"]}},{"container_id":{"operator":"=","values":["1"]}}]`

## CREATE a file link

To create a link between a file and a work package we need make a POST request, containing the storage ID, the original file ID (i.e. Nextcloud's `fileid`) and the work package ID.

Example: "Create a link between work package 2 and file 1234 in storage 1."

`POST /api/v3/file_links`

with payload

```json
{
"storageId" : 1,
"originId" : 1234,
"workPackageId" : 2
}
```

The return value will be the created `FileLink` resource as described above.

## DELETE a file link

Example: _"Delete file link with ID 1."_

`DELETE /api/v3/file_links/1`

## Nice to have: UPDATE origin data of a file link

It might be necessary to offer a way to update the origin data of a file link as files attributes could change at its origin, such as its file name, mime type, last modified timestamp and the name of the person that last modified the file. However, I am not sure if we will really need it in the first version.