Skip to main content
PATCH
https://aodocs.altirnao.com
/
api
/
document
/
v1
/
{documentId}
Modify document attachments
curl --request PATCH \
  --url https://aodocs.altirnao.com/api/document/v1/{documentId}
{
  "kind": "aodocs#document",
  "libraryName": "my-DMS-lib-001",
  "className": "my-dms-class-002",
  "className_i18n": "my-dms-class-002",
  "libraryId": "RnTG8PDu8ZqTuDVHcv",
  "classId": "RnTf1mx35gaTJLzoFp",
  "id": "RnTzVT2x5Sb48h3vSQ",
  "title": "Hello-world-doc-001", // ⇐ new, overwrote the old
  "richText": "This is my <b>Hello world!</b> document." // ⇐ new, overwrote the old
  ...
}

​
Method and API

Play with the API Explorer:

PATCH /document/v1/\{documentId\}

​
Guidelines

​
Prerequisites

Because this is an overwrite operation, you have to know which pieces you want to replace with your new changes, including overwriting with nothing (deleting). And you have to be aware of the power of this operation to make changes that are somewhat complicated to undo.

​
Request

Only documentId is mandatory (to identify which document’s metadata to alter). However, including only the documentId parameter is the degenerate case: if that’s all you specify, and specify no changes, then the modificationDate and updateAuthor of the document get reset, but otherwise no changes take place. For this method to do anything, you must specify the parts you want changed, and you must send them as request-body parameters (not as query parameters).

​
Attachment array fields

Attachments are represented in the ApiDocument resource as an array field (see preceding warning under “Modifying array fields”). As with any other field, when the field is sent to the server, its contents will ```PATCH“ (overwrite) the contents of the corresponding field on the target resource residing on the server. To alter what files are currently attached to your document, use the array field called attachments in the body of the request. This array field holds the file ID(s) of Drive files you want to become the current attachments to your document. TF/SF In the case of TF/SF documents, this is relatively foolproof since you are limited to a single attachment. There is only one action that carries any risk, and that’s replacing the attachment with another one by accidentally sending a non-empty attachments array field. See the following “Sample request body (attachments non-empty)”. DMS On the other hand, when dealing with DMS-document attachments, you must proceed more cautiously because DMS documents have no attachment restrictions, and you must thus consider multiple potential outcomes depending on how you phrase attachments. If you are using the attachments array field in your request and you happen to be dealing with a DMS document, then you must exercise caution: whatever you include in the array (including nothing) becomes your new list of attachments, in the order you provide. Sending array field with data vs. empty This means that if you are actually including the attachments array field in your request, then you must explicitly specify what you want to keep each time; and if you send it to the server empty, the server will empty the target document of all its attachments. For example, if you have an existing DMS document with one attachment, but want to add another attachment to it, you must specify both attachments (the existing and the new), and in the correct order. If you only specify the new attachment, the original attachment will get detached, and your new attachment will get attached in its place, replacing the original. Result: a single attachment (the new one). Therefore, if you do not need to change anything to do with attachments, do not send the attachments array field at all. This ensures that the attachments array field in the resource on the server remains unmodified, keeping your attachments as they are.
Tip:You can avoid some of the pitfalls of array fields by sampling the contents of the array field from the previous PATCH operation which returns the ApiDocument resource in full (or partial if you used the fields field to filter the response. This is the same result as sending a GET request to get a document. This way you always have an up-to-date listing of what the target resource looks like on the server. Read the array field(s) you need, and feed the fields into your next request.
Note:Notwithstanding attachment-restriction differences between DMS documents and TF/SF ones, the preceding guidelines for using the attachments array fields are generalizable to other array fields.

​
Sample request body (attachments non-empty)

When you send the attachments array field filled out with file ID(s), you are saying to the server that you want these files in this specific order to be the attachments from now on, regardless of what used to be attached up until now. In the case of TF/SF, you are restricted to exactly one file ID inside the attachments array field. In the case of DMS, this restriction does not exist. To keep any current attachments in your DMS document, you must explicitly state them here. Also, if you want to keep their existing ordering, then you also must specify them in that order. 
PATCH https://aodocs.altirnao.com/api/document/v1/RsjbYc788vqY6WDeUnM

{
  "attachments": // ⇐ removes all current links to Drive files and replaces them with whatever is specified in the square brackets that follow
  [
    {
      "fileId": "1s1uFfW8GHPZ0fUpvwdT-oCsrY7G9QndAU"
    },
    {
      "fileId": "1QvvRHb8XmLYlB66ZZf-fzoTVVDYfrNxO0"
    }
  ]
}

​
Sample request body (DMS-only, with attachments array field empty)

In DMS, this is how you detach (“delete”) attachments all at once. The (ex-)attachments are still owned by the storage account. With no parent document, however, no reference to them exists in either AODocs libraries or in Drive (except in logs). To regain access to them you need the intervention of a domain administrator. 
PATCH https://aodocs.altirnao.com/api/document/v1/RsjbYc788vqY6WDeUnM

{
  "attachments": []  // ⇐ removes all current links to Drive files and replaces them with whatever is specified in the square brackets (empty square brackets means all attachments get detached!)
}

​
Sample request body (with attachments array field not included)

PATCH https://aodocs.altirnao.com/api/document/v1/RsjbYc788vqY6WDeUnM

{
}   // not including the attachments array field in the body keeps attachments as they are, unmodified

​
Responses

The response returns an ApiDocument resource, listing the freshly modified document with the overwritten fields and everything else unmodified). If you included the attachments array field in your request, the response includes the new content. 
{
  "kind": "aodocs#document",
  "libraryName": "my-DMS-lib-001",
  "className": "my-dms-class-002",
  "className_i18n": "my-dms-class-002",
  "libraryId": "RnTG8PDu8ZqTuDVHcv",
  "classId": "RnTf1mx35gaTJLzoFp",
  "id": "RnTzVT2x5Sb48h3vSQ",
  "title": "Hello-world-doc-001", // ⇐ new, overwrote the old
  "richText": "This is my <b>Hello world!</b> document." // ⇐ new, overwrote the old
  ...
}