ApostropheCMSMedia APIs
The @apostrophecms/attachment module manages all media file uploading. Once uploaded, an attachment object should typically be added to an Apostrophe piece or page document (including, but not limited to, @apostrophecms/image and @apostrophecms/file pieces). It is not common, and not generally recommended, to leave uploaded attachments unconnected from any Apostrophe document.
For attachments meant to be included in the media or file libraries, metadata and organization those media are primarily managed through the respective @apostrophecms/image and @apostrophecms/file piece types. See the pieces REST API documentation for additional information.
Endpoints
| Method | Path | Description | Auth required |
|---|---|---|---|
POST | /api/v1/@apostrophecms/attachment/upload | Upload a media file | TRUE |
POST | /api/v1/@apostrophecms/attachment/crop | Crop an image file | TRUE |
GET | /api/v1/@apostrophecms/image | Get an image document with a specified ID | FALSE |
POST | /api/v1/@apostrophecms/image | Insert a new image | TRUE |
GET | /api/v1/@apostrophecms/file | Get a file document with a specified ID | FALSE |
POST | /api/v1/@apostrophecms/file | Insert a new file | TRUE |
POST /api/v1/@apostrophecms/attachment/upload
Authentication required.
The body of the request should use the multipart/form-data encoding, with the file itself uploaded under the name file. In a client-side request, the body of the request should be a FormData object.
Request example
// Create a `FormData` object
const formData = new window.FormData();
// Append a file as per the FormData API:
// https://developer.mozilla.org/en-US/docs/Web/API/FormData/append
formData.append('file', myfile);
// Request inside an async function.
const attachment = await fetch('/api/v1/@apostrophecms/attachment/upload', {
method: 'POST',
headers: {
'Content-Type': 'multipart/form-data'
},
body: formData
});Response
The successful POST request returns the newly created attachment. In case of an error an appropriate HTTP status code is returned.
| Property | Format | Description |
|---|---|---|
_id | String | A unique and permanent ID for the attachment |
_url | String | The file URL (the original size, if an image) |
_urls | Object | An object with keys for the generated image size variants, if an image file |
archivedDocIds | Array | An array of string IDs that represent image or file documents using this attachment that are archived |
createdAt | Date | An ISO date string of the attachment's creation date and time |
docIds | Array | An array of string IDs that represent image or file documents using this attachment (empty at initial upload) |
extension | String | The file's file extension, e.g., png, pdf |
group | String | The associated file group, including image or office by default |
height | Number | Height of the image file, if an image |
landscape | Boolean | true if an image with landscape aspect ratio |
length | Number | The file size in bytes |
md5 | String | MD5 checksum value for the file |
name | String | A "slugified" version of the file name (generally lowercased and joined with dashes) |
portrait | Boolean | true if an image with portrait aspect ratio |
title | String | A "sortified" version of the file name (case-insensitive) |
type | String | 'attachment' |
updatedAt | Date | An ISO date string of the attachment's last update date and time |
width | Number | Width of the image file, if an image |
// This is a PNG upload with filename `blue-box.png`
{
"_id": "ckj0akbxa003vp39kfbxgb8zg",
"group": "images",
"createdAt": "2020-12-22T17:58:11.314Z",
"name": "blue-box",
"title": "blue box",
"extension": "png",
"type": "attachment",
"docIds": [],
"archivedDocIds": [],
"length": 10497,
"md5": "630eeaaecd0bdc07c4a82eeca4c07588",
"width": 600,
"height": 106,
"landscape": true,
"_urls": {
"max": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.max.png",
"full": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.full.png",
"two-thirds": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.two-thirds.png",
"one-half": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-half.png",
"one-third": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-third.png",
"one-sixth": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.one-sixth.png",
"original": "https://example.net/uploads/attachments/ckj0akbxa003vp39kfbxgb8zg-blue-box.png"
}
}POST /api/v1/@apostrophecms/attachment/crop
Authentication required.
This route uploads a new, cropped version of an existing image. The crop object is appended to the crops array property of the attachment document.
The body of the request should include:
| Property | Format | Description |
|---|---|---|
_id | String | The _id property of an existing image attachment document |
crop | Object | An object containing top, left, width and height properties |
The newly uploaded image file will be stored with a file name using the crop properties as well as the _id, name, and file extension of the original attachment, formatted as {_id}-{name}.{top}.{left}.{width}.{height}.{extension}
Response
The successful POST request returns true. In case of an error an appropriate HTTP status code is returned.
Media GET request
Endpoints:
GET /api/v1/@apostrophecms/imageGET /api/v1/@apostrophecms/file
A GET request for an image or file is generally a normal piece type GET request. In addition to the typical piece document properties, it will also include an attachment property, containing an object similar to one returned from an attachment upload request.
Media POST request
Authentication required.
POST /api/v1/@apostrophecms/imagePOST /api/v1/@apostrophecms/file
A POST request for an image or file is generally a normal piece type POST request. In addition to the typical piece document properties, it must also include an attachment property, containing the attachment object returned from an attachment upload request.