NAV
php

Gallery handling

If you want to host the uploaded images yourself and want to use your other hosted images as well, then there are a few routes to fulfil this functionality.

Basic operations: The user uploads an image in the api to our server, which uploads it to the given server. This requires you to implement an upload route on your server and configure our server (you have to do the configuration only once). The user can delete the images as well, so there should be an delete route on your server (it should be in the gallery configuration) .

We will create a md5 hash from a timestamp and your magic word (The right order of the string concatenation: timestam + magic word). This two (the hash and the timestamp) will be sent to you in each of our requests (in the query). You recreate the hash in your server side and compare the two hashes. With this method you can ensure that the request really came from us.

Upload route

You should implement a route on your server which we can use for image upload.

Type: POST

We will upload the images as the following. There will be “userId”, “hash” and “time” fields in the query of the request: - The “userId” will contain the id of the user (who wants to upload the image). - The “hash” will be a string we use for authenticate ourself. We concatenate timestamp with your magic word (the right order of the concatenation: timestam + magicword) and create an md5 hash from it. With this hash you can ensure that the request came from us. - The “time” will be the timestamp we used for creating the hash

The image will be uplaoded as a file (the field name will be “file”) and there will be another field “userId”, it will contain the same data as the query field “userId”. There is a third field, called “originalFileName” which contains the name of the original file before the user started to upload it.
Please note that if you use php on your server side then checking the content-tpye of the uploaded image with the $_Files[“file”][“type”] is not possible (it will be Application/octet-stream) but if you use our hash to authenticate us, then you do not have to worry about the uploaded file. We will make sure that it will be what it has to be.

If you progress our request by php, reading our sent data may need a special way like the example below:

$json = file_get_contents(“php://input”); $values = json_decode($json, true);

$someValue = $values[“someValue”];

Further info about this issue can be read in this article: http://stackoverflow.com/questions/11990767/post-empty-when-curling-json

The response to our post request should be a json object. The object should have the following properties: * url {String} /REQUIRED/ The url where the newly uploaded image can be found. * secure_url {String} Http secure version og the image url * thumb_url {String} An url where the thumbnail version of the image is available (Tha gallery can work a lot faster if you can provide a thumbnail) * name {String} The name of the image. If it is not given then we will you the last segment of the url * width {Number} The original width of the image (It can save a lot of process if you can provide this information) * height {Number} The original height of the image (It can save a lot of process if you can provide this information)

Or if you want to response with some kind of error (for example an error message), then you have to send an error object with the following property: * err

For example:
var error = { err: “Not my user!” };

Delete route

You should implement a route on your server side which we can use for deleting images.

Type: POST

There will be “hash” and “time” fields in the query of the request: - The “hash” will be a string we use for authenticate ourself. We concatenate timestamp with your magic word (the right order of the concatenation: timestam + magicword) and create an md5 hash from it. With this hash you can ensure that the request came from us. - The “time” will be the timestamp we used for creating the hash

We will post an object with two parameters: * url {String} The url of the deleted image * userId {String} The id of the user who deleted the image.

If you progress our request by php, reading our sent data may need a special way like the example below:

$json = file_get_contents(“php://input”); $values = json_decode($json, true);

$someValue = $values[“someValue”];

Further info about this issue can be read in this article: http://stackoverflow.com/questions/11990767/post-empty-when-curling-json

Your response to our post request should be 200. (HTTP status code)
Or if you want to response with some kind of error (for example an error message), then you have to send an error object with the following property: * err

For example:
var error = { err: “Not my user!” };

Copy route

IF you want to copy a project from a user to an other and want to copy the images (which are used in the project) too, you need to use the create from to with images route. This route will collect the urls of the images (which you host) of the project and send it to you. After that you should make a copy of this images to the target user and sent us back the parameters of this new images.

Type: POST

There will be “hash” and “time” fields in the query of the request: - The “hash” will be a string we use for authenticate ourself. We concatenate timestamp with your magic word (he right order of the concatenation: timestam + magicword) and create an md5 hash from it. With this hash you can ensure that the request came from us. - The “time” will be the timestamp we used for creating the hash

We will post an object whit the following parameters: * urls {Array} It contains the urls of the images which are used in the template * from_userId {String} The id of the users from who we want to copy the template to the target user * target_userId {String} The id of the user who will get the new template. (This user needs the new urls)

If you progress our request by php, reading our sent data may need a special way like the example below:

$json = file_get_contents(“php://input”); $values = json_decode($json, true);

$someValue = $values[“someValue”];

Further info about this issue can be read in this article: http://stackoverflow.com/questions/11990767/post-empty-when-curling-json

Your response to our post request should be an object. The object should have an “urls” property which should be another object. This object should have the following “key - value” pairs: the old url (which you get from the urls array we sent with the post request) should be the key and the value should be the parameters of the new image (like the one you need to send beack in the upload route: * url {String} /REQUIRED/ The url where the newly uploaded image can be found. * secure_url {String} Http secure version og the image url * thumb_url {String} An url where the thumbnail version of the image is available (Tha gallery can work a lot faster if you can provide a thumbnail) * name {String} The name of the image. If it is not given then we will you the last segment of the url * width {Number} The original width of the image (It can save a lot of process if you can provide this information) * height {Number} The original height of the image (It can save a lot of process if you can provide this information)

For example: If we uploaded the following array: [“www.foo.bar”, “http://test.com/image.jpg”] then your asnwer should be something like this object:

var answer = { urls: { “www.foo.bar”: { url: “www.copy.of.foo.bar” }, “http://test.com/image.jpg”: { url: “http://test.com/copyimage.jpg”, secure_url: “https://test.com/copyimage.jpg”, thumb_url: “http://test.com/thumb/copyimage.jpg”, name: “copyimage.jpg”, width: 600, height: 200 } } };

Or if you want to response with some kind of error (for example an error message), then you have to send an error object with the following property: * err

For example:
var error = { err: “Not my user!” };

Configure the api’s gallery.

Type
Route

Parameters (you should post):

Response:

The data you posted: - uploadRoute {String} - deleteRoute {String} - copyRoute {String} - noUploadText {Object} - limitReached {Object} - noUrl {Boolean} or it can be an error object: - err Description of the error {String} or an error code {Number}.

Get configuration

Gets the configuration of the api gallery.

Type
Route

Response:

Config object: - uploadRoute {String} The route you set for the uploading or nothing if you not configured our server yet. - deleteRoute {String} The route you set for the deleting or nothing if you not configured our server yet. - copyRoute {String} The route you set for the create from to width images route (only if you previously set it) - noUploadText {Object} (only if you previously set it in) - limitReached {Object} (only if you previously set it) - noUrl {Boolean} (only if you previously set it true)

or it can be an error object: - err Description of the error {String} or an error code {Number}.

List images

Lists all images of a specified user

Type
Route

Parameters (optionals):

Parameters (in the route):

Response:

Array of urls

Or in case of of limit and skip parameters sent an Object consists of: - totalCount {Number} The length of the full list - result {Array} The list of the urls, same as above

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Add images

Add one or more images to one or more specified users

Type
Route

Parameters (you should post):

Response:

Three different array: - added {Array} contains the image user pairs which were successfully created. An object in this array looks like this: - image {Object} One image from the posted images array - users {Array} An array containing the ids of the users whose get the image successfully - alreadyHave {Array} contains the image user pairs where the user alread had the given image. An object in this array looks like this: - image {Object} One image from the posted images array - users {Array} An array containing the ids of the users whose already had this image - failed {Array} contains the image user pairs where the adding the image to the given users failed. An object in this array looks like this: - image {Object} One image from the posted images array - users {Array} An array containing the ids of the users whose cannot get the image because of somekind of error - error {String} Description of the error

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Delete images

Delete one or more images from one or more specified users

Type
Route

Parameters (you should post):

Response:

Three different array: - deleted {Array} contains the image user pairs where the image was successfully deleted. An object in this array looks like this: - image {Object} One image from the posted images array - url {String} The url of the image - users {Array} An array containing the ids of the users whose - dontHave {Array} contains the image user pairs where the user doesn’t have the given image. An object in this array looks like this: - image {Object} One image from the posted images array - url {String} The url of the image - users {Array} An array containing the ids of the users whose doesn’t have this image - failed {Array} contains the image user pairs where the deleting the image from the given users failed. An object in this array looks like this: - image {Object} One image from the posted images array - users {Array} An array containing the ids of the users whose image cannot be deleted because of somekind of error - error {String} Description of the error

or it can be an error object: - err Description of the error {String} or an error code {Number}.

Tutorials

Tutorial Description
The Basics In this tutorial you will learn about our dashboard, the access token generation and the very basic functionalities, like creating and opening projects.
Admin Functionalities The biggest take away of this tutorial that you will see how to create new users in our system, so you will be able to associate one user for each of users in your system.
Old Built-in Gallery Configuration In this tutorial you will learn about how to set up the gallery properly, how to implement the hooks on your side and you will also learn about the security of these hooks.

Other documentations

Document Description
Basics This documentation covers the very basics of the integration, like:
  • generating an access token
  • making API calls
  • managing and opening projects
  • managing users
  • gallery handling
Advanced This documentation covers more advanced topics. Probably you will only need some of these functionalities.
  • Group handling
  • String placeholders
  • Dynamic data
  • Favorite elements’ management
  • Working with custom data
  • Advanced project handling
  • API key management
postMessage API By reading this documentation you can learn about how to manipulate the editor itself from the client side. Basically this client side API is based on the postMessage function with which you can send messages between frames from different domains.
  • Basic messages and responses (eg. manual save)
  • Hooking on editor events (eg. using your own gallery instead of the built-in one)
  • Dynamic data
  • Setting elements’ properties
Element descriptors A detailed description of our element types used in projects and favorite elements. We generate all of our outputs based on these JSON descriptors.
Old built-in gallery Don’t use it. Use the new postMessage based solution.
Migrating to the CDN based editor In this article you will learn about how to migrate from the good old version of the editor to the superfast and robust CDN based version.

Example implementations

Our PHP examples are very well maintained, but the others are probably not up-to-date. Still, they can be a good starting point, but you might want to take a look at the PHP examples as well in the meanwhile.

If you have another example implementation, please let us know, we will fork it and will put a link here.

php