API : Files

GET file

Return data about the specified file.

Request

GET /files/:id

Response

{
  "id": 1,
  "url": "/files/1",
  "file_urls": {
    "original": "http://yourdomain.com/files/original/2b42672de6e47a67698a52e1415bd2c0.pdf",
    "fullsize": "http://yourdomain.com/files/fullsize/2b42672de6e47a67698a52e1415bd2c0.jpg",
    "thumbnail": "http://yourdomain.com/files/thumbnails/2b42672de6e47a67698a52e1415bd2c0.jpg",
    "square_thumbnail": "http://yourdomain.com/files/square_thumbnails/2b42672de6e47a67698a52e1415bd2c0.jpg"
  },
  "item": {"id": 1, "url": "/items/1"},
  "order": null,
  "size": 1953540,
  "has_derivative_images": true,
  "authentication": "f6089bca39470e8c19410242061b1f78",
  "mime_type": "audio/mpeg",
  "type_os": "MPEG ADTS, v1, 128 kbps, 44.1 kHz, JntStereo",
  "filename": "54a21c1552feef92069d504fbaf145a8.mp3",
  "original_filename": "1ATwUDzA3SCU.128.mp3",
  "added": "2013-03-27T08:17:37+00:00",
  "modified": "2013-04-21T15:05:07+00:00", 
  "stored": true,
  "metadata": {},
  "element_texts": [
    {
      "html": false,
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "element_set": {"id": 1, "url": "/element_sets/1", "name": "Dublin Core"},
      "element": {"id": 1, "url": "/elements/1", "name": "Title"}
    }
  ]
}

Note on "metadata"

The metadata object contains data extracted by the getId3 library, and so its structure and content will vary widely based on the file type, what data the library is able to extract, and what data is embedded in the file.

Possible properties within metadata (if it is not empty) are: mime_type, video, audio, comments, comments_html, iptc, jpg. mime_type within metadata is a string, and can differ from the mime_type property in the top level of the response. All other properties will be objects.

GET files

Return data about files.

Request

GET /files

Parameters

• item: integer
• order: integer
• size_greater_than: integer
• has_derivative_image: boolean
• mime_type: string
• added_since: string (ISO 8601)
• modified_since: string (ISO 8601)

Response

An array of JSON file representations (see above).

POST files

Create a new file. Only one file may be uploaded at a time.

Request

POST /files

Requests must use the multipart/form-data content type. The content disposition name for the file must be file. The content disposition name for the JSON data must be data. We highly recommend that you use a HTTP client that is capable of encoding form-data requests for you, but the typical request should look something like this:

POST /api/files HTTP/1.1
Content-Type: multipart/form-data; boundary=E19zNvXGzXaLvS5C

----E19zNvXGzXaLvS5C
Content-Disposition: form-data; name="data"

{
  "order": 2,
  "item": {
    "id": 1,
  }
  "element_texts": [
    {
      "html": false,
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "element": {"id": 1}
    }
  ]
}
----E19zNvXGzXaLvS5C
Content-Disposition: form-data; name="file"; filename="example.pdf"
Content-Type: application/pdf

...contents of example.pdf...
----E19zNvXGzXaLvS5C

Response

Location: http://yourdomain.com/api/files/:id

An JSON representation of the newly created file (see above).

PUT file

Edit an existing file.

Request

PUT /files/:id

{
  "order": 2,
  "element_texts": [
    {
      "html": false,
      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "element": {"id": 1}
    }
  ]
}

Response

An JSON representation of the newly edited file (see above).

DELETE file

Delete a file.

Request

DELETE /files/:id

Response

A 204 No Content response.

Errors

In addition to the general errors, requests to the files resource may return the following errors:

• 400 Bad Request
  • Invalid request. Request body must be a JSON object.
  • Invalid request. Exactly one file must be uploaded per request.
  • Invalid request. Missing JSON data.
  • Invalid item. File must belong to an existing item.
• 500 Internal Server Error
  • Invalid request. The default job dispatcher must be synchronous.