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 namedfile_name
and obtain an upload token. Theobject_type
needs to validate some property of the file uploaded as the mime type. For example the image object type will acceptimage/jpeg
but will rejectvideo/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: - Authorization – (required) access token
- Content-Type – (required) the content type of the file
- Content-Length – (required) the size of the file
Response Headers: - Content-Type – application/json
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
andUPLOAD_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.