FamilyWall API

{{>toc}}

h1. Media Management

Uploading/downloading/managing pictures with the JSON apis

h2. Upload

Uploading pictures is taking place using Multipart POST http request. For instance, using ctccreate2 api to create a contact is going like that:

<pre>

> 265001916915724 Content-Disposition: form-data; name="a01call"

ctccreate2

> 265001916915724 Content-Disposition: form-data; name="a01firstName"

testupload

> 265001916915724 Content-Disposition: form-data; name="a01pictures.0"; filename="Lighthouse.jpg" Content-Type: image/jpeg

<actual binary content going here>...

...

</pre>

> Encoding: *UTF8*. By default form-data of type text (such as a01firstName) is decoded by the server in UTF8. Note that this differs from the common usage which requires that the default charset is ISO-8859-1. However you can override this encoding by setting a content type: Content-Type: text/plain;charset=ISO-8859-1

As defined by the apis, several pictures can be uploaded for contacts, events, or poi but for the moment in the application, only one is used, so the post parameter name is always "axxpictures.0"

During the api call the content will be retrieved by the server and stored in the media storage. A unique URI will be generated for this content and sent back in the response. For instance for contact:

<pre>

"r":{

        "contactId":"42_1040",

        "accountId":"23",

        "pictureURIs":[

          "http:\/\/localhost:8080\/media\/42_3341l94r_582?"

        ],

        "firstName":"testupload",

        "displayName":"testupload",

        "devices":[],

        "addresses":[]

      }

</pre>

pictureURIs is the array of picture associated with this contact (even if we currently only use one picture). 

Note how the / is escaped by the JSON format using backslashes.

Please note that if size below 1MB, pictures are stored as-is in the media storage of the server, and accounts for the quota of the user.

If size of uploaded picture is abode 1MB, pictures are resized by the server to 1000x1000, in jpeg (stragegy is KEEPRATIO_REDUCE, see below for explaination about resize strategy, but the aspect ratio is kept).

So in order to preserve the user's quota, caution should be taken not to upload fat pictures. 

For instance it is recommended to use a jpeg encoding with a quality setting of 0.7 (which is usually enough) and reduced size (for instance 1024pixel of width) instead of the full 5Mpx size of modern smartphones).

When you re-size those pictures, take caution not to go above 1MB, because if you go above this limit, the server will resize them again.

h2. Downloading pictures from the server:

One can use the URI to retrieve the picture from the server directly. The pictureURIs contains cryptographic key to ensure nobody can "guess" pictures uris.

But remember that having the URI is solely enough to get access to the picture. The system is not checking that the user is correctly logged-in.

As a result, pictures URIS shall be somehow protected and not directly visible by the user.

The server is able (and shall be used) to resize the picture to fit the screen UI instead of doing that client-side. This enables to save some bandwidth by reducing

the picture size server-side.

The syntax is http://localhost:8080/media/42_3341l94r_582?w=<desiredWidth>&h=<desiredHeight>"

The server will resize the picture using the desiredWidth and desiredHeight (for instance http://localhost:8080/media/42_3341l94r_582?w=2000&h=400)

The server will not distord the picture but will keep the aspect ratio of the picture. For instance, here we asked for a picture of size 2000x400, however the

original aspect ratio of the picture is 4/3. Therefore the server will build the biggest image that both be included in the 2000x400 but keep the aspect ratio

of 4/3, so it will resize the picture to 533x400. The client must then center this image within the 2000x400 placeholder in the UI, giving a letterboxed version of the image.

Special care shall be taken to use common picture size over all clients (web/android/iphone/windowsPhone/etc) in order to reduce the computing effort of the resizing server-side.

The resizing result is cached on the server, so to reduce the storage space of those thumbnails, common format shall be used.

For instance, we shall decide that all thumbnails of the application across all devices may be either "SMALL" 80x60 or "LARGE" 240x160.

h3. Optional stragegy for resizing pictures

Optionally, you can define the resize strategy for downloading picture using the "s" parameters.

For instance: http://localhost:8080/media/42_3341l94r_582?w=<desiredWidth>&h=<desiredHeight>&s=<REDIM_STRATEGY>

REDIM_STRATEGY can be:

* KEEPRATIO_FIT, // result will not have asked dimension (one will be smaller)

* KEEPRATIO_REDUCE, (r) // same as KEEPRATIO_FIT but reduce only, if the image is smaller than asked dimension nothing is done

* FIT, (f) // result will have exact asked dimension (but with distortion)

* CROP, (c) // result will have exact asked dimension (but without some part of the image)

* PAD (p) // => KEEPRATIO_FIT with an extra empty canvas to fill asked dimension;

In parenthesis is the letter to use for <REDMIN_STRATEGY>. For instance s=f will indicate to use FIT. If you want to use "KEEPRATIO_FIT", don't add the s parameter.

h2. Management of pictures

Pictures are automatically deleted when their parent element (being the contact/event/poi or message) is deleted.