com.atlassian.confluence.plugins.restapi.resources

Class AttachmentResource

java.lang.Object

com.atlassian.confluence.plugins.restapi.resources.AttachmentResource

public class AttachmentResource
extends Object

CRUD operations for Attachments on Content.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AttachmentResource.ConfluenceAttachmentMultipartConfig

Constructor Summary

Constructors

Constructor and Description
AttachmentResource(AttachmentService attachmentService, SettingsService settingsService)

Method Summary

Modifier and Type	Method and Description
RestList<Content>	createAttachments(ContentId containerId, ContentStatus containerStatus, List<com.atlassian.plugins.rest.common.multipart.FilePart> fileParts, List<com.atlassian.plugins.rest.common.multipart.FilePart> comments, List<com.atlassian.plugins.rest.common.multipart.FilePart> minorEdits, List<com.atlassian.plugins.rest.common.multipart.FilePart> hiddens) Add one or more attachments to a Confluence Content entity, with optional comments.
RestList<Content>	getAttachments(ContentId contentId, String expand, int start, int limit, String filename, String mediaType, javax.ws.rs.core.UriInfo uriInfo) Returns a paginated list of attachment Content entities within a single container.
Content	update(String attachmentId, Content attachment) Update the non-binary data of an Attachment.
Content	updateData(ContentId attachmentId, com.atlassian.plugins.rest.common.multipart.FilePart filePart, com.atlassian.plugins.rest.common.multipart.FilePart comment, com.atlassian.plugins.rest.common.multipart.FilePart minorEdit, com.atlassian.plugins.rest.common.multipart.FilePart hidden) Update the binary data of an Attachment, and optionally the comment and the minor edit field.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AttachmentResource

public AttachmentResource(AttachmentService attachmentService,
                          SettingsService settingsService)

Method Detail

getAttachments

@PublicApi
public RestList<Content> getAttachments(ContentId contentId,
                                                   String expand,
                                                   int start,
                                                   int limit,
                                                   String filename,
                                                   String mediaType,
                                                   @Context
                                                   javax.ws.rs.core.UriInfo uriInfo)
                                            throws ServiceException

Returns a paginated list of attachment Content entities within a single container.

Example request URI(s):

• http://example.com/rest/api/content/1234/child/attachment?start=0&limit=10
• http://example.com/rest/api/content/1234/child/attachment?filename=myfile.txt&expand=version,container

Parameters:

contentId - a string containing the id of the attachments content container

expand - a comma separated list of properties to expand on the Attachments returned. Optional.

start - the index of the first item within the result set that should be returned. Optional.

limit - how many items should be returned after the start index. Optional.

filename - (optional) filter parameter to return only the Attachment with the matching file name. Optional.

mediaType - (optional) filter parameter to return only Attachments with a matching Media-Type. Optional.

uriInfo - (injected) information about the request URI

Returns:

a JSON representation of the content, or a 404 NOT FOUND if there is no content with the given containerId or if the user is not permitted.

Throws:

ServiceException

createAttachments

@PublicApi
public RestList<Content> createAttachments(ContentId containerId,
                                                      ContentStatus containerStatus,
                                                      List<com.atlassian.plugins.rest.common.multipart.FilePart> fileParts,
                                                      @Nullable
                                                      List<com.atlassian.plugins.rest.common.multipart.FilePart> comments,
                                                      @Nullable
                                                      List<com.atlassian.plugins.rest.common.multipart.FilePart> minorEdits,
                                                      @Nullable
                                                      List<com.atlassian.plugins.rest.common.multipart.FilePart> hiddens)
                                               throws ServiceException

Add one or more attachments to a Confluence Content entity, with optional comments.

Comments are optional, but if included there must be as many comments as there are files, and the comments must be in the same order as the files.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to attach a file called "myfile.txt" to the container with id "123", with a comment included:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" -F "comment=This is my File" http://myhost/rest/api/content/123/child/attachment

A example to attach a file called "myfile.txt" to the container with id "123", with a comment, and set the minorEdits flag to be true:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" -F "minorEdit=true" -F "comment=This is my File" http://myhost/rest/api/content/123/child/attachment

An example to attach the same file, with no comment:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/content/123/child/attachment

Example request URI(s):

• http://example.com/rest/api/content/1234/child/attachment

Parameters:

containerId - a string containing the content id of the attachments content container

containerStatus - a string containing the status of the attachments content container, supports current or draft, defaults to current

fileParts - a list of fileparts containing the data for each attachment to be created

comments - (optional) a list of comments matching the list of attachment data. If supplied, the size of this list must match the size of the fileParts list

minorEdits - (optional) form parameter indicating whether the attachments should be minorEdits. If minorEdits is set to true, no notification email will be generated for that attachment.

hiddens - (optional) form parameter indicating whether the attachments should be hidden. If hidden is set to true, no notification email or activity stream will be generated for that attachment.

Returns:

a JSON representation of the attachments added.

Throws:

ServiceException

update

@PublicApi
public Content update(String attachmentId,
                                 Content attachment)
                          throws ServiceException

Update the non-binary data of an Attachment.

This resource can be used to update an attachment's filename, media-type, comment, and parent container.

Example request URI(s):

• http://example.com/rest/api/content/1234/child/attachment/5678

Parameters:

attachmentId - the id of the attachment to update

attachment - the details of the Attachment to be updated

Returns:

a JSON representation of the attachment after being updated.

Throws:

ServiceException

updateData

@PublicApi
public Content updateData(ContentId attachmentId,
                                     com.atlassian.plugins.rest.common.multipart.FilePart filePart,
                                     com.atlassian.plugins.rest.common.multipart.FilePart comment,
                                     com.atlassian.plugins.rest.common.multipart.FilePart minorEdit,
                                     com.atlassian.plugins.rest.common.multipart.FilePart hidden)
                              throws ServiceException

Update the binary data of an Attachment, and optionally the comment and the minor edit field.

This adds a new version of the attachment, containing the new binary data, filename, and content-type.

When updating the binary data of an attachment, the comment related to it together with the field that specifies if it's a minor edit can be updated as well, but are not required. If an update is considered to be a minor edit, notifications will not be sent to the watchers of that content.

This resource expects a multipart post. The media-type multipart/form-data is defined in RFC 1867. Most client libraries have classes that make dealing with multipart posts simple. For instance, in Java the Apache HTTP Components library provides a MultiPartEntity that makes it simple to submit a multipart POST.

In order to protect against XSRF attacks, because this method accepts multipart/form-data, it has XSRF protection on it. This means you must submit a header of X-Atlassian-Token: nocheck with the request, otherwise it will be blocked.

The name of the multipart/form-data parameter that contains attachments must be "file"

A simple example to upload a file called "myfile.txt" to the Attachment with id "456" in a container with id "123", with the comment updated, and minorEdit set to true:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" -F "minorEdit=true" -F "comment=This is my updated File" http://myhost/rest/api/content/123/child/attachment/456/data

An example to upload the same file, with no comment:

curl -D- -u admin:admin -X POST -H "X-Atlassian-Token: nocheck" -F "file=@myfile.txt" http://myhost/rest/api/content/123/child/attachment/456/data

Example request URI(s):

• http://example.com/rest/api/content/1234/child/attachment/5678/data

Parameters:

attachmentId - the id of the attachment to upload a new file for

filePart - the file to be uploaded

comment - the comment to associate with the attachment - may be a blank string

minorEdit - (optional) form parameter indicating whether the attachment should be a minorEdit. If minorEdit is set to true, no notification email will be generated for that attachment.

hidden - (optional) form parameter indicating whether the attachment should be hidden. If hidden is set to true, no notification email or activity stream will be generated for that attachment.

Returns:

a JSON representation of the attachments added.

Throws:

ServiceException