TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
OpenProject is the leading open source project management software.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
35326 Commits
139 Branches
203 Tags
1.2 GiB
 
 
 
 
 
 
Tag: Branch: Tree: 2e828009f5
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '2e828009f5'
${ noResults }
openproject/docs/api/apiv3/endpoints/attachments.apib

1011 lines
36 KiB
Raw Blame History

# Group Attachments
Attachments are files that were uploaded to OpenProject. Each attachment belongs to a single
container (e.g. a work package or a board message).
## Actions
| Link | Description | Condition |
|:-------------------:|----------------------------------------------------------------------| -------------------------------------------- |
| delete | Deletes this attachment | **Permission**: edit on attachment container or being the author for attachments without container |
## Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|:----------------:| --------------------------------------------------- | ------------- | ----------- | -------------------- |
| self | This attachment | Attachment | not null | READ |
| container | The object (e.g. WorkPackage) housing the attachment| Anything | not null | READ |
| author | The user who uploaded the attachment | User | not null | READ |
| downloadLocation | Direct download link to the attachment | - | not null | READ |
## Local Properties
| Property | Description | Type | Constraints | Supported operations |
|:------------:| ----------------------------------------------- | ----------- | ----------- | -------------------- |
| id | Attachment's id | Integer | x > 0 | READ |
| title | The name of the file | String | not null | READ |
| fileName | The name of the uploaded file | String | not null | READ |
| fileSize | The size of the uploaded file in Bytes | Integer | x >= 0 | READ |
| description | A user provided description of the file | Formattable | not null | READ |
| contentType | The files MIME-Type as determined by the server | String | not null | READ |
| digest | A checksum for the files content | Digest | not null | READ |
| createdAt | Time of creation | DateTime | not null | READ |
## Attachments [/api/v3/attachments]
## Create Attachment [POST]
Clients can create attachments without a container first and attach them later on.
This is useful if the container does not exist at the time the attachment is uploaded.
After the upload, the client can then claim such containerless attachments for any resource eligible (e.g. WorkPackage) on subsequent requests.
The upload and the claiming *must* be done for the same user account. Attachments uploaded by another user cannot be claimed and
once claimed for a resource, they cannot be claimed by another.
The upload request must be of type `multipart/form-data` with exactly two parts.
The first part *must* be called `metadata`. Its content type is expected to be `application/json`,
the body *must* be a single JSON object, containing at least the `fileName` and optionally the attachments `description`.
The second part *must* be called `file`, its content type *should* match the mime type of the file.
The body *must* be the raw content of the file.
Note that a `filename` *must* be indicated in the `Content-Disposition` of this part, although it will be ignored.
Instead the `fileName` inside the JSON of the metadata part will be used.
+ Request (multipart/form-data)
--boundary-delimiter
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"fileName": "cute-cat.png",
"description": {
"raw": "A cute kitty, cuddling with its friends!"
}
}
--boundary-delimiter
Content-Disposition: form-data; name="file"; filename="attachment"
Content-Type: image/png
PNG file data
--boundary-delimiter--
+ Response 200 (application/hal+json)
[Attachment][]
+ Response 400 (application/hal+json)
Returned if the client sends a not understandable request. Reasons include:
* Omitting one of the required parts (metadata and file)
* sending unparsable JSON in the metadata part
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request could not be parsed as JSON."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** At least one permission in any project: edit work package, add work package, edit messages, edit wiki pages (plugins might extend this list)
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete this attachment."
}
+ Response 422 (application/hal+json)
Returned if the client tries to send an invalid attachment.
Reasons are:
* Omitting the file name (`fileName` property of metadata part)
* Sending a file that is too large
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "File is too large (maximum size is 5242880 Bytes)."
}
## Attachment [/api/v3/attachments/{id}]
+ Model
+ Body
{
"_type": "Attachment",
"_links": {
"self": {
"href": "/api/v3/attachments/1"
},
"container" {
"href": "/api/v3/work_packages/1"
},
"author": {
"href": "/api/v3/users/1"
},
"downloadLocation": {
"href": "/attachments/1/download"
}
},
"id": 1,
"fileName": "cat.png",
"filesize": 24,
"description": {
"format": "plain",
"raw": "A picture of a cute cat",
"html": "<p>A picture of a cute cat</p>"
},
"contentType": "image/png",
"digest": {
"algorithm": "md5",
"64c26a8403cd796ea4cf913cda2ee4a9":
},
"createdAt": "2014-05-21T08:51:20Z"
}
## View attachment [GET]
+ Parameters
+ id (required, integer, `1`) ... Attachment id
+ Response 200 (application/hal+json)
[Attachment][]
+ Response 404 (application/hal+json)
Returned if the attachment does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view permission for the container of the attachment or being the author for attachments without container
*Note: A client without sufficient permissions shall not be able to test for the existence of an attachment.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified attachment does not exist."
}
## Delete attachment [DELETE]
Permanently deletes the specified attachment.
+ Parameters
+ id (required, integer, `1`) ... Attachment id
+ Response 204
Returned if the attachment was deleted successfully.
Note that the response body is empty as of now. In future versions of the API a body
*might* be returned along with an appropriate HTTP status.
+ Body
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** edit permission for the container of the attachment or being the author for attachments without container
*Note that you will only receive this error, if you are at least allowed to see the attachment.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete this attachment."
}
+ Response 404 (application/hal+json)
Returned if the attachment does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view permission for the container of the attachment or being the author for attachments without container
*Note: A client without sufficient permissions shall not be able to test for the existence of an attachment.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified attachment does not exist."
}
# Attachments by post [/api/v3/posts/{id}/attachments]
+ Model
+ Body
{
"_type": "Collection",
"total": 1,
"count": 1,
"_embedded": {
"elements": [
{
"_type": "Attachment",
"id": 376,
"fileName": "some.gif",
"fileSize": 3521772,
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"contentType": "image/gif",
"digest": {
"algorithm": "md5",
"hash": "7ac9c97ef73d47127f590788b84c0c1c"
},
"createdAt": "2018-06-01T07:24:19Z",
"_links": {
"self": {
"href": "/api/v3/attachments/376",
"title": "200.gif"
},
"author": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"container": {
"href": "/api/v3/posts/72",
"title": "wiki"
},
"downloadLocation": {
"href": "/api/v3/attachments/376/content"
},
"delete": {
"href": "/api/v3/attachments/376",
"method": "delete"
}
}
}
]
},
"_links": {
"self": {
"href": "/api/v3/posts/72/attachments"
}
}
}
## List attachments [GET]
+ Parameters
+ id (required, integer, `1`) ... ID of the post whose attachments will be listed
+ Response 200 (application/hal+json)
[Attachments by post][]
+ Response 404 (application/hal+json)
Returned if the post does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view messages
*Note: A client without sufficient permissions shall not be able to test for the existence of a post.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## Add attachment [POST]
Adds an attachment with the post as it's container.
See [the general specification for uploading attachments](#attachments-attachments) for details.
+ Parameters
+ id (required, integer, `1`) ... ID of the post to receive the attachment
+ Request (multipart/form-data)
--boundary-delimiter
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"fileName": "cute-cat.png",
"description": {
"raw": "A cute kitty, cuddling with its friends!"
}
}
--boundary-delimiter
Content-Disposition: form-data; name="file"; filename="attachment"
Content-Type: image/png
PNG file data
--boundary-delimiter--
+ Response 200 (application/hal+json)
+ Body
{
"_embedded": {
"author": {
"_type": "User",
"id": 1,
"name": "OpenProject Admin",
"createdAt": "2015-03-20T12:56:52Z",
"updatedAt": "2018-05-29T13:57:44Z",
"login": "admin",
"admin": true,
"firstName": "OpenProject",
"lastName": "Admin",
"email": null,
"avatar": "",
"status": "active",
"identityUrl": null,
"_links": {
"self": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"showUser": {
"href": "/users/1",
"type": "text/html"
},
"updateImmediately": {
"href": "/api/v3/users/1",
"title": "Update admin",
"method": "patch"
},
"lock": {
"href": "/api/v3/users/1/lock",
"title": "Set lock on admin",
"method": "post"
}
}
},
"container": {
"_type": "Post",
"id": 150,
"subject": "sfsdfsdfsdfsdf",
"_links": {
"self": {
"href": "/api/v3/posts/150"
},
"attachments": {
"href": "/api/v3/posts/150/attachments"
},
"addAttachment": {
"href": "/api/v3/posts/150/attachments",
"method": "post"
},
"project": {
"href": "/api/v3/projects/12",
"title": "Demo project"
}
}
}
},
"_type": "Attachment",
"id": 377,
"fileName": "some.gif",
"fileSize": 3521772,
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"contentType": "image/gif",
"digest": {
"algorithm": "md5",
"hash": "7ac9c97ef73d47127f590788b84c0c1c"
},
"createdAt": "2018-06-01T07:53:36Z",
"_links": {
"self": {
"href": "/api/v3/attachments/377",
"title": "200.gif"
},
"author": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"container": {
"href": "/api/v3/posts/150",
"title": "sfsdfsdfsdfsdf"
},
"downloadLocation": {
"href": "/api/v3/attachments/377/content"
},
"delete": {
"href": "/api/v3/attachments/377",
"method": "delete"
}
}
}
+ Response 400 (application/hal+json)
Returned if the client sends a not understandable request. Reasons include:
* Omitting one of the required parts (metadata and file)
* sending unparsable JSON in the metadata part
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request could not be parsed as JSON."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** edit messages
*Note that you will only receive this error, if you are at least allowed to see the wiki page*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete this attachment."
}
+ Response 404 (application/hal+json)
Returned if the post does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view messages
*Note: A client without sufficient permissions shall not be able to test for the existence of a post.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
+ Response 422 (application/hal+json)
Returned if the client tries to send an invalid attachment.
Reasons are:
* Omitting the file name (`fileName` property of metadata part)
* Sending a file that is too large
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "File is too large (maximum size is 5242880 Bytes)."
}
# Attachments by wiki page [/api/v3/wiki_pages/{id}/attachments]
+ Model
+ Body
{
"_type": "Collection",
"total": 1,
"count": 1,
"_embedded": {
"elements": [
{
"_type": "Attachment",
"id": 376,
"fileName": "some.gif",
"fileSize": 3521772,
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"contentType": "image/gif",
"digest": {
"algorithm": "md5",
"hash": "7ac9c97ef73d47127f590788b84c0c1c"
},
"createdAt": "2018-06-01T07:24:19Z",
"_links": {
"self": {
"href": "/api/v3/attachments/376",
"title": "200.gif"
},
"author": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"container": {
"href": "/api/v3/wiki_pages/72",
"title": "wiki"
},
"downloadLocation": {
"href": "/api/v3/attachments/376/content"
},
"delete": {
"href": "/api/v3/attachments/376",
"method": "delete"
}
}
}
]
},
"_links": {
"self": {
"href": "/api/v3/wiki_pages/72/attachments"
}
}
}
## List attachments [GET]
+ Parameters
+ id (required, integer, `1`) ... ID of the wiki page whose attachments will be listed
+ Response 200 (application/hal+json)
[Attachments by wiki page][]
+ Response 404 (application/hal+json)
Returned if the wiki page does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view wiki pages
*Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
## Add attachment [POST]
Adds an attachment with the wiki page as it's container.
See [the general specification for uploading attachments](#attachments-attachments) for details.
+ Parameters
+ id (required, integer, `1`) ... ID of the wiki page to receive the attachment
+ Request (multipart/form-data)
--boundary-delimiter
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"fileName": "cute-cat.png",
"description": {
"raw": "A cute kitty, cuddling with its friends!"
}
}
--boundary-delimiter
Content-Disposition: form-data; name="file"; filename="attachment"
Content-Type: image/png
PNG file data
--boundary-delimiter--
+ Response 200 (application/hal+json)
+ Body
{
"_embedded": {
"author": {
"_type": "User",
"id": 1,
"name": "OpenProject Admin",
"createdAt": "2015-03-20T12:56:52Z",
"updatedAt": "2018-05-29T13:57:44Z",
"login": "admin",
"admin": true,
"firstName": "OpenProject",
"lastName": "Admin",
"email": null,
"avatar": "",
"status": "active",
"identityUrl": null,
"_links": {
"self": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"showUser": {
"href": "/users/1",
"type": "text/html"
},
"updateImmediately": {
"href": "/api/v3/users/1",
"title": "Update admin",
"method": "patch"
},
"lock": {
"href": "/api/v3/users/1/lock",
"title": "Set lock on admin",
"method": "post"
}
}
},
"container": {
"_type": "WikiPage",
"id": 72,
"title": "wiki",
"_links": {
"self": {
"href": "/api/v3/wiki_pages/72"
},
"attachments": {
"href": "/api/v3/wiki_pages/72/attachments"
},
"addAttachment": {
"href": "/api/v3/wiki_pages/72/attachments",
"method": "post"
},
"project": {
"href": "/api/v3/projects/12",
"title": "Demo project"
}
}
}
},
"_type": "Attachment",
"id": 376,
"fileName": "some.gif",
"fileSize": 3521772,
"description": {
"format": "plain",
"raw": "",
"html": ""
},
"contentType": "image/gif",
"digest": {
"algorithm": "md5",
"hash": "7ac9c97ef73d47127f590788b84c0c1c"
},
"createdAt": "2018-06-01T07:24:19Z",
"_links": {
"self": {
"href": "/api/v3/attachments/376",
"title": "200.gif"
},
"author": {
"href": "/api/v3/users/1",
"title": "OpenProject Admin"
},
"container": {
"href": "/api/v3/wiki_pages/72",
"title": "wiki"
},
"downloadLocation": {
"href": "/api/v3/attachments/376/content"
},
"delete": {
"href": "/api/v3/attachments/376",
"method": "delete"
}
}
}
+ Response 400 (application/hal+json)
Returned if the client sends a not understandable request. Reasons include:
* Omitting one of the required parts (metadata and file)
* sending unparsable JSON in the metadata part
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request could not be parsed as JSON."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** edit wiki pages
*Note that you will only receive this error, if you are at least allowed to see the wiki page*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete this attachment."
}
+ Response 404 (application/hal+json)
Returned if the wiki page does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view wiki pages
*Note: A client without sufficient permissions shall not be able to test for the existence of a wiki page
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
+ Response 422 (application/hal+json)
Returned if the client tries to send an invalid attachment.
Reasons are:
* Omitting the file name (`fileName` property of metadata part)
* Sending a file that is too large
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "File is too large (maximum size is 5242880 Bytes)."
}
# Attachments by work package [/api/v3/work_packages/{id}/attachments]
+ Model
+ Body
{
"_links": {
"self": { "href": "/api/v3/work_packages/1/attachments" }
},
"total": 2,
"count": 2,
"_type": "Collection",
"_embedded":
{
"elements": [
{
"_type": "Attachment",
"_links": {
"self": {
"href": "/api/v3/attachments/1"
},
"container" {
"href": "/api/v3/work_packages/1"
},
"author": {
"href": "/api/v3/users/1"
},
"downloadLocation": {
"href": "/attachments/1/download"
}
},
"id": 1,
"fileName": "cat.png",
"filesize": 24,
"description": {
"format": "plain",
"raw": "A picture of a cute cat",
"html": "<p>A picture of a cute cat</p>"
},
"contentType": "image/png",
"digest": {
"algorithm": "md5",
"64c26a8403cd796ea4cf913cda2ee4a9":
},
"createdAt": "2014-05-21T08:51:20Z"
},
{
"_type": "Attachment",
"_links": {
"self": {
"href": "/api/v3/attachments/2"
},
"container" {
"href": "/api/v3/work_packages/1"
},
"author": {
"href": "/api/v3/users/1"
},
"downloadLocation": {
"href": "/attachments/2/download"
}
},
"id": 2,
"fileName": "cat2.png",
"filesize": 24,
"description": {
"format": "plain",
"raw": "A picture of another cute cat",
"html": "<p>A picture of another cute cat</p>"
},
"contentType": "image/png",
"digest": {
"algorithm": "md5",
"46c26a8403cd769ea4c9f13cdae2e49a":
},
"createdAt": "2014-05-21T08:51:20Z"
}
]
}
}
## List attachments [GET]
+ Parameters
+ id (required, integer, `1`) ... ID of the work package whose attachments will be listed
+ Response 200 (application/hal+json)
[Attachments by work package][]
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view work package
*Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
## Add attachment [POST]
To add an attachment to a work package, a client needs to issue a request of type `multipart/form-data`
with exactly two parts.
The first part *must* be called `metadata`. Its content type is expected to be `application/json`,
the body *must* be a single JSON object, containing at least the `fileName` and optionally the attachments `description`.
The second part *must* be called `file`, its content type *should* match the mime type of the file.
The body *must* be the raw content of the file.
Note that a `filename` must be indicated in the `Content-Disposition` of this part, however it will be ignored.
Instead the `fileName` inside the JSON of the metadata part will be used.
+ Parameters
+ id (required, integer, `1`) ... ID of the work package to receive the attachment
+ Request (multipart/form-data)
--boundary-delimiter
Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8
{
"fileName": "cute-cat.png",
"description": {
"raw": "A cute kitty, cuddling with its friends!"
}
}
--boundary-delimiter
Content-Disposition: form-data; name="file"; filename="attachment"
Content-Type: image/png
PNG file data
--boundary-delimiter--
+ Response 200 (application/hal+json)
[Attachment][]
+ Response 400 (application/hal+json)
Returned if the client sends a not understandable request. Reasons include:
* Omitting one of the required parts (metadata and file)
* sending unparsable JSON in the metadata part
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request could not be parsed as JSON."
}
+ Response 403 (application/hal+json)
Returned if the client does not have sufficient permissions.
**Required permission:** edit work package or add work package
*Note that you will only receive this error, if you are at least allowed to see the work package.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not allowed to delete this attachment."
}
+ Response 404 (application/hal+json)
Returned if the work package does not exist or the client does not have sufficient permissions
to see it.
**Required permission:** view work package
*Note: A client without sufficient permissions shall not be able to test for the existence of a work package.
That's why a 404 is returned here, even if a 403 might be more appropriate.*
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The specified work package does not exist."
}
+ Response 422 (application/hal+json)
Returned if the client tries to send an invalid attachment.
Reasons are:
* Omitting the file name (`fileName` property of metadata part)
* Sending a file that is too large
+ Body
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "File is too large (maximum size is 5242880 Bytes)."
}