Files upload /files

It is used to upload files that must be linked to an object, generally multimedia objects as image, video, audio,...

The file upload flow is described in Uploading files section.

Warning

At the moment uploaded files are only linkable to new BEdita objects that support upload. You can’t change file associated to an existing object.

Upload a file

POST /files/(string: object_type)/(string: file_name)

Upload a file related to an object_type and named file_name and obtain an upload token. The object_type needs to validate some property of the file uploaded as the mime type. For example the image object type will accept image/jpeg but will reject video/mp4.

file_name should be the original file name url encoded.

Important

To write an object it has to be configured to be writable

$config['api'] = array(
    // ....
    'validation' => array(
        // to save 'document' and 'event' object types
        'writableObjects' => array('document', 'event')
    )
);

User has to be authenticated and the request body must contain the binary file data.

Request Headers:
 
Response Headers:
 
Status Codes:
  • 200 OK – Success, the file was uploaded. The response body will contain the upload token
  • 400 Bad Request – Required parameters are missing or the request is malformed or some validation fails.
  • 401 Unauthorized – Request is not authorized
  • 403 Forbidden – The quota available or the max number of files allowed is exceeded. The UPLOAD_QUOTA_EXCEEDED and UPLOAD_FILES_LIMIT_EXCEEDED Error codes helps to distinguish which quota exceeds the limit.
  • 409 Conflict – The file is already present

Example request:

POST /files/image/foo.jpg HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: image/jpeg
Content-Length: 284

raw image content

Example response:

HTTP/1.1 200 Success
Content-Type: application/json

{
  "api": "files",
  "data": {
      "upload_token": "80fdd2590b609d51873fe187d65f026e39748179"
  },
  "method": "post",
  "params": [],
  "url": "https://example.com/api/files/image/foo.jpg"
}

Once obtained the upload token it must be used to finalize the upload action creating a new object linked to the file uploaded. You can do it using POST /objects and passing the upload token in the request data payload.

Example

POST /objects HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
    "data": {
        "title": "Uploaded via API!",
        "object_type": "image",
        "upload_token": "80fdd2590b609d51873fe187d65f026e39748179",
        "parents": [1]
    }
}
HTTP/1.1 201 Created
Content-Type: application/json

{
  "api": "objects",
  "data": {
      "id": 57,
      "title": "Uploaded via API!",
      "object_type": "image",
      "name": "foo.jpg",
      "original_name": "foo.jpg",
      "mime_type": "image/jpeg",
      "uri": "https://assets.example.com/cd/df/foo.jpg",
      "file_size": 284,
      "width": 200,
      "height": 100
  },
  "method": "post",
  "params": [],
  "url": "https://example.com/api/objects"
}

Note

In this example the image object created is located on publication tree. See POST /objects to know the required paramters creating an object.