Images API
==========

The Image API supports uploading and editing images that could be used as splash post image, teaser, social teaser and even other features than posts such as authors creation.

Ratios
------

Every site in RebelMouse platform has its own image crops configured, these settings are useful when a image is going to be rezised or cropped. So they are considered in every process related to images, and each resized or cropped image has usually a different purpose depending on page type.

By default, we have the following ratios configured:

+----------+----+------------+
|Title     |Code|Sizes       |
+==========+====+=====+======+
|Super Wide|3x1 | - 1200x400 |
|          |    | - 600x200  |
+----------+----+-----+------+
|Wide      |2x1 | - 1200x600 |
|          |    | - 600x300  |
+----------+----+-----+------+
|Medium    |3x2 | - 1200x800 |
|          |    | - 600x400  |
+----------+----+-----+------+
|Square    |1x1 | - 600x600  |
|          |    | - 300x300  |
+----------+----+-----+------+
|Tall      |9x16| - 700x1245 |
+----------+----+-----+------+
|Widescreen|16x9| - 1245x700 |
+----------+----+-----+------+

Uploading images
----------------

Upload a image sending its content as a part of HTTP request body or sending a URL as part of a JSON document.

.. code:: json

   POST /api/1.3/images

Parameters
**********

================ ====== ===============================
Name             Type   Description
================ ====== ===============================
``image_url``    String A image URL location - Optional
``caption``      String Caption - Optional
``photo_credit`` String Photo credit - Optional
``alt``          String Alt/Title - Optional
================ ====== ===============================

.. note::

   * Multiple files can be also sent as part of HTTP request. They are used only
     if ``image_url`` is not used in HTTP request.
   * For requests with "multipart/form-data" content type, files should be named
     with "file".

Example with multipart/form-data
********************************

.. code::

   POST /api/1.3/images HTTP/1.1
   HOST: <domain>
   x-rmauth: <api key>
   authorization: Basic <base64 encoded credentials>
   content-type: multipart/form-data; boundary=----WebKitFormBoundarym59pe8dwmBaESksR
   content-length: <content length>

   ------WebKitFormBoundarym59pe8dwmBaESksR
   Content-Disposition: form-data; name="file"; filename="image.png"
   Content-Type: image/png

   <file content>
   ------WebKitFormBoundarym59pe8dwmBaESksR--

.. note::

   Files to be considered for uploading must be named with "file" string.

Response
********

For a single image uploaded:

.. code:: json

   {
		"is_animated_gif": false,
		"task_id": "c3e2a367-24cb-426f-9179-457a0e0ea9ec",
		"height": 511,
		"shortcode_id": "7229TA1498262817",
		"iptc": {
			"by-line": "",
			"caption/abstract": ""
		},
		"id": <id>,
		"shortcode_params": {
			"is_animated_gif": false,
			"crop_info": "%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A",
			"original_size": "512x511",
			"expand": 1
		},
		"thumbnails": {
			"origin": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg",
			"35x35": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/35x35.jpg",
			"1200x800": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x800.jpg",
			"480x270": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/480x270.jpg",
			"700x1245": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/700x1245.jpg",
			"980x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg",
			"600x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x.jpg",
			"600x600": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x600.jpg",
			"960x540": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/960x540.jpg",
			"600x300": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x300.jpg",
			"210x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/210x.jpg",
			"300x": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/300x.jpg",
			"600x400": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/600x400.jpg",
			"1200x600": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/1200x600.jpg"
		},
		"manual_image_crops": {
			"16x9": {
				"width": 512,
				"top": 222,
				"height": 289,
				"left": 0,
				"sizes": [
					"960x540",
					"480x270"
				]
			},
			"2x1": {
				"width": 512,
				"top": 255,
				"height": 256,
				"left": 0,
				"sizes": [
					"1200x600",
					"600x300"
				]
			},
			"3x2": {
				"width": 512,
				"top": 169,
				"height": 342,
				"left": 0,
				"sizes": [
					"1200x800",
					"600x400"
				]
			},
			"1x1": {
				"width": 109,
				"top": 402,
				"height": 109,
				"left": 0,
				"sizes": [
					"600x600"
				]
			},
			"9x16": {
				"width": 117,
				"top": 303,
				"height": 208,
				"left": 0,
				"sizes": [
					"700x1245"
				]
			}
		},
		"filename": "image_hmXa6R.jpg",
		"width": 512,
		"media_html": "<img src=\"https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/980x.jpg\" id=\"89b1c\" class=\"rm-shortcode\" data-rm-shortcode-id=\"7229TA1498262817\" data-rm-shortcode-name=\"rebelmouse-image\" >",
		"shortcode": "[rebelmouse-image <id> is_animated_gif=false crop_info=\"%22%7B%22image%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%22thumbnails%22%3A%20%7B%22origin%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2Forigin.jpg%22%2C%20%2235x35%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F35x35.jpg%22%2C%20%221200x800%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x800.jpg%22%2C%20%22480x270%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F480x270.jpg%22%2C%20%22700x1245%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F700x1245.jpg%22%2C%20%22980x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F980x.jpg%22%2C%20%22600x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x.jpg%22%2C%20%22600x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x600.jpg%22%2C%20%22960x540%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F960x540.jpg%22%2C%20%22600x300%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x300.jpg%22%2C%20%22210x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F210x.jpg%22%2C%20%22300x%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F300x.jpg%22%2C%20%22600x400%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F600x400.jpg%22%2C%20%221200x600%22%3A%20%22https%3A%2F%2Fs3.amazonaws.com%2Fdev-assets.rbl.ms%2F%3Cid%3E%2F1200x600.jpg%22%7D%2C%20%22manual_image_crops%22%3A%20%7B%2216x9%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20222%2C%20%22height%22%3A%20289%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22960x540%22%2C%20%22480x270%22%5D%7D%2C%20%222x1%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20255%2C%20%22height%22%3A%20256%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x600%22%2C%20%22600x300%22%5D%7D%2C%20%223x2%22%3A%20%7B%22width%22%3A%20512%2C%20%22top%22%3A%20169%2C%20%22height%22%3A%20342%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%221200x800%22%2C%20%22600x400%22%5D%7D%2C%20%221x1%22%3A%20%7B%22width%22%3A%20109%2C%20%22top%22%3A%20402%2C%20%22height%22%3A%20109%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22600x600%22%5D%7D%2C%20%229x16%22%3A%20%7B%22width%22%3A%20117%2C%20%22top%22%3A%20303%2C%20%22height%22%3A%20208%2C%20%22left%22%3A%200%2C%20%22sizes%22%3A%20%5B%22700x1245%22%5D%7D%7D%7D%22%0A\" original_size=\"512x511\" expand=1]",
		"image_original_url": "https://s3.amazonaws.com/dev-assets.rbl.ms/<id>/origin.jpg"
   }

For multiple images uploaded:

It takes the same schema for each image uploaded but in form of an array.

Editing images
--------------

Editing an image for creating some others with certain dimensions.


.. code:: json

   PUT /api/1.3/images/<id>

Parameters
**********

====================== ====== ==========================================
Name                   Type   Description
====================== ====== ==========================================
``image_url``          String A image URL location - Required
``manual_image_crops`` Object Crop setting for resizing image - Optional
``caption``            String Caption - Optional
``photo_credit``       String Photo credit - Optional
====================== ====== ==========================================

Manual Image Crops
******************

It depends on ratios configured per site. It must be a objects, whose keys must be the ratio codes and the values should contain the following information:

============= ======= ============================
Name          Type    Description
============= ======= ============================
``top``       Integer Absolute top coordinate
``left``      Integer Absolute left coordinate
``height``    Integer Absolute height coordinate
``width``     Integer Absolute width coordinate
``imgHeight`` Integer Width of the original image
``imgWidth``  Integer Height of the original image
============= ======= ============================

Example
~~~~~~~

.. code::

   {
	"16x9": {
		"top": 222,
		"left": 0,
		"height": 289,
		"width": 512,
		"imgWidth": 512,
		"imgHeight": 511
	},
	"2x1": {
		"top": 255,
		"left": 0,
		"height": 256,
		"width": 512,
		"imgWidth": 512,
		"imgHeight": 511
	},
	"3x2": {
		"top": 169,
		"left": 0,
		"height": 342,
		"width": 512,
		"imgWidth": 512,
		"imgHeight": 511
	},
	"1x1": {
		"top": 402,
		"left": 0,
		"height": 109,
		"width": 109,
		"imgWidth": 512,
		"imgHeight": 511
	},
	"9x16": {
		"top": 303,
		"left": 0,
		"height": 208,
		"width": 117,
		"imgWidth": 512,
		"imgHeight": 511
	}
   }

Response
********

It takes the same schema than uploading images. Only one image is permitted to edit per request.