Developers

Assets

Assets are image files used within the Site's content blocks.

Summary of asset endpoints

List all available assets for the current site

GET /assets

By default, this requests returns a list of all assets for the current site (newer first).

Asset may be on of type: image, document or flash.

When asset type is image then also all array of available sizes are included to response as sizes.

When asset type is image or flash then attributes width and height is provided in response.

Example response:

Status: 200 OK
[
  {
    "id": 2,
    "filename": "report.pdf",
    "content_type": "application/pdf",
    "size": 36657,
    "extension": "pdf",
    "type": "document",
    "created_at": "2014-02-04T14:37:41.000Z",
    "updated_at": "2014-02-04T14:37:41.000Z",
    "url": "http://helloworld.voog.co/admin/api/assets/2",
    "public_url": "http://media.voog.com/0000/0000/0001/files/report.pdf"
  }, {
    "id": 1,
    "filename": "Screen Shot 2014-01-28 at 10.53.26.png",
    "content_type": "image/png",
    "size": 5305339,
    "extension": "png",
    "type": "image",
    "created_at": "2014-02-04T10:55:28.000Z",
    "updated_at": "2014-02-04T10:55:30.000Z",
    "url": "http://helloworld.voog.co/admin/api/assets/1",
    "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26.png",
    "sizes": [
      {
        "thumbnail": "huge",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_huge.png",
        "content_type": "image/png",
        "size": 211910,
        "width": 2048,
        "height": 1365,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_huge.png"
      },
      {
        "thumbnail": "large",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_large.png",
        "content_type": "image/png",
        "size": 114420,
        "width": 1280,
        "height": 853,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_large.png"
      },
      {
        "thumbnail": "block",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_block.png",
        "content_type": "image/png",
        "size": 31876,
        "width": 500,
        "height": 333,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_block.png"
      },
      {
        "thumbnail": "medium",
        "filename": "Screen Shot 2014-01-28 at 10.53.26_medium.jpg",
        "content_type": "image/jpeg",
        "size": 5904,
        "width": 150,
        "height": 100,
        "public_url": "http://media.voog.com/0000/0000/0001/photos/Screen%20Shot%202014-01-28%20at%2010.53.26_medium.jpg"
      }
    ],
    "width": 5184,
    "height": 3456
  }
]

Parameters

  • per_page - elements per response (default: 50; maximum: 250).
  • page - requested page (default: 1).
  • media_set_id - media set id (eg 1). Returns only assets for requested media set.
  • name - filter assets by filename. Usage examples:
    • ?name=somename - returns all assets where filename begins with "somename" (e.g. "somename.jpg", "somename-for-gallery.jpg").
    • ?name=*somename - returns all assets where filename contains string "somename" (e.g. "file-somename.jpg", "somename-for-gallery.jpg").
    • ?name=.jpg - returns all assets where file extension is "jpg" (e.g. "file-somename.jpg", "somename-for-gallery.jpg").

Filter attributes

Read more about filters.

  • Object asset attributes: id, filename, content_type, size, created_at, updated_at.
  • Object media_set attributes: id, title, created_at, updated_at.

Create new asset

After new asset object is created, it response includes upload_url and confirm_url that is needed to complete a file upload.

After the file is successfully uploaded to given upload_url a request to confirm_url completes uploading process (see Asset confirmation).

POST /assets

Example response:

Status: 201 Created
{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:03:11.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "upload_url": "http://media.voog.com/0000/0000/001/files/new_image.png?AWSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Expires=1391528261&Signature=IGPxxxxxxxx%2FdjkdjkJWjwjjwjw%3D",
  "confirm_url": "http://helloworld.voog.co/admin/api/assets/3/confirm"
}

Parameters

Required parameters:

  • filename - unique filename (if file with same name exist then numbered suffix (e.g. "-1") is appended automatically to new file). (E.g. "my-new file.png")
  • size - file size in bytes (e.g. 95708).
  • content_type - content type for file (e.g. "image/jpeg").

Confirm asset upload

PUT /assets/1/confirm

This request completes uploading process after new asset object is created and successfully uploaded to given upload_url.

Example request:

PUT http://helloworld.voog.co/admin/api/assets/3/confirm

Example response:

Status: 201 Created
{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:04:01.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image.png",
  "sizes": [
    {
      "thumbnail": "block",
      "filename": "new_image_block.png",
      "content_type": "image/png",
      "size": 124204,
      "width": 500,
      "height": 344,
      "public_url": "http://media.kraftal.com/0000/0000/0001/photos/new_image_block.png"
    },
    {
      "thumbnail": "medium",
      "filename": "new_image_medium.jpg",
      "content_type": "image/jpeg",
      "size": 4887,
      "width": 150,
      "height": 103,
      "public_url": "http://media.kraftal.com/0000/0000/0001/photos/new_image_medium.jpg"
    }
  ],
  "width": 880,
  "height": 550
}

Parameters

Optional parameters:

  • media_set_id - ID of the media set (gallery) the asset should be added to

Uploading assets

Here's a basic example based on the previous asset create request:

PUT http://media.voog.com/0000/0000/0001/files/new_image.png?AWSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Expires=1391528261&Signature=IGPxxxxxxxx%2FdjkdjkJWjwjjwjw%3D

Headers:

x-amz-acl: public-read
content-type: image/png
content-length: 95708

The request body has to be the raw file data as a byte array (Buffer in NodeJS, Blob in Javascript etc.).
For more details, refer to the official Amazon AWS documentation.

Code example in Ruby.

Code example in Node.

Get data for a single asset

GET /admin/api/assets/1

Get detailed data for single asset. Asset may be on of type: image, document or flash.

When asset type is image then also all array of available sizes are included to response as sizes.

When asset type is image or flash then attributes width and height is provided in response.

Example request:

GET http://helloworld.voog.co/admin/api/assets/3?include_media_sets=true

Example response:

Status: 200 OK
{
  "id": 3,
  "filename": "new_image.png",
  "content_type": "image/png",
  "size": 95708,
  "extension": "png",
  "type": "image",
  "created_at": "2014-02-04T11:03:11.000Z",
  "updated_at": "2014-02-04T11:04:01.000Z",
  "url": "http://helloworld.voog.co/admin/api/assets/3",
  "public_url": "http://media.voog.com/0000/0000/0001/photos/new_image.png",
  "sizes": [
    {
      "thumbnail": "block",
      "filename": "new_image_block.png",
      "content_type": "image/png",
      "size": 124204,
      "width": 500,
      "height": 344,
      "public_url": "http://media.kraftal.com/0000/0000/0001/photos/new_image_block.png"
    },
    {
      "thumbnail": "medium",
      "filename": "new_image_medium.jpg",
      "content_type": "image/jpeg",
      "size": 4887,
      "width": 150,
      "height": 103,
      "public_url": "http://media.kraftal.com/0000/0000/0001/photos/new_image_medium.jpg"
    }
  ],
  "width": 880,
  "height": 550,
  "media_sets": [{
    "id": 1,
    "title": "",
    "created_at": "2014-01-16T08:04:27.000Z",
    "updated_at": "2014-01-16T08:04:27.000Z",
    "url": "http://media.voog.com/admin/api/media_sets/1",
    "add_assets_url": "http://media.voog.com/admin/api/media_sets/1/add_assets"
  }]
}

Parameters

  • include_media_sets - includes list of media sets where current asset is added. (E.g. ?include_media_sets=true)

Remove an asset

DELETE /assets/1

This request deletes the asset from the database. Asset thumbnails are deleted automatically with parent.

Example request:

DELETE http://helloworld.voog.co/admin/api/assets/1

Example response:

Status: 204 No Content