Last updated 2016-07-01

Metapic REST API Documentation

Welcome to the Metapic REST API documentation.
This documentation covers all the basic concepts of the API from authentication to how to consume the Metapic API resource endpoints.

Authentication

The Metapic API uses a secret key based request signing process. Each request is signed individually using a HMAC encrypted with SHA256. Every request is always signed with your client id and a timestamp. The timestamp key is called mtpc_timestamp. The request signing should also include all post data or other variables where applicable. In order to create the string for the HMAC function these variables are sorted in key order and then concatenated to a string in the format "var1=x&var2=y...". This string is then sent to the HMAC function with your secret key as the HMAC key.

Examples

Assuming that your client id is 123456 and that the current time is 2014-03-04 11:50:00 you would get the following keys for signing: 

{
	"client_id": 123456,
	"mtpc_timestamp": "2014-03-04 11:50:00"
}

These keys are concatenated to the following string: "client_id=123456&mtpc_timestamp=2014-03-04 11:50:00". This string is then sent to the HMAC function along with the secret key.

The returned hash from the HMAC function is then sent as a query variable called access_token. Given the data above a request for users would look like this: http://api.metapic.dev/users?access_token=hashed_accesstoken&client_id=123456

REST API Endpoints

Users

The users endpoint is used for accessing and modifying the users connected to your client account.

GET /users

http://localhost/users
Response

Returns all users connected to your client account, sorted on created date in descending order.

GET /users/user_id

http://localhost/users/876
Response

Fetches a user based on user id.

Parameters
user_id Part of the endpoint url. Unsigned integer.

POST /users

http://localhost/users
Response

Create a new Metapic user.
The user will automatically be linked to your account.

Parameters
username Max 24 alphanumeric characters
email Valid email adress. Unique.
password At least 6 characters.

PUT /users/user_id

http://localhost/users/876
Response

Updates a Metapic user.
Returns the modified user as a json object.

Parameters
user_id Part of the endpoint url. Unsigned integer.
username Max 24 alphanumeric characters
email Valid email adress. Must be unique.
password At least 6 characters.

DELETE /users/user_id

http://localhost/users/876
Response

Deletes a Metapic user. Returns the deleted user as json object.

Parameters
user_id Part of the endpoint url. Unsigned integer.

Images

The images endpoint is used for accessing and modifying the images connected to your client account.

GET /images

http://localhost/images?user_id=1
Response

Returns all images connected to your client account, sorted on created date in descending order.
If a user_id is provided it will return all images related to that user.

Parameters
include_tags Whether to include the image tags in the request. Boolean.
user_id The id of the user to fetch images from. Unsigned integer.

GET /images/image_id

http://localhost/images/876
Response

Fetches an image based on image id.

Parameters
image_id REQUIRED Part of the endpoint url. Unsigned integer.
include_tags Whether to include the image tags in the request. Boolean.

POST /images

http://localhost/images
Response

Create a new Metapic image.
The image will automatically be linked to your account.

Parameters
user_id REQUIRED The user_id of the Metapic user this image belongs to.
url The url for the image.
site The site the image is being displayed on.
width Image width in pixels.
height Image height in pixels.

PUT /images/image_id

http://localhost/images/876
Response

Updates a Metapic image.
Returns the modified image as a json object.

Parameters
image_id REQUIRED Part of the endpoint url. Unsigned integer.
url The url for the image.
site The site the image is being displayed on.
width Image width in pixels.
height Image height in pixels.

DELETE /images/image_id

http://localhost/images/876
Response

Deletes a Metapic image. Returns the deleted image as json object.

Parameters
image_id REQUIRED Part of the endpoint url. Unsigned integer.

PUT /images/upload

http://localhost/images/upload

Uploads an image to metapic server.

Parameters
user_id REQUIRED user_id for the connected user. Unsigned integer.
imageData base64 encoded image

Tags

The tags endpoint is used for accessing and modifying the tags connected to your client account.

GET /tags

http://localhost/tags
Response

Returns all tags connected to your client account, sorted on created date in descending order.
If an image_id is provided it will return all tags related to that image.
If a user_id is provided it will return all tags related to that user.

Parameters
image_id The id of the image to fetch tags for. Unsigned integer.
user_id The id of the user to fetch tags for. Unsigned integer.
no_image Gives hit only when no image is connected. Boolean.

GET /tags/tag_id

http://localhost/tags/123
Response

Fetches a tag based on tag id.

Parameters
tag_id Part of the endpoint url. Unsigned integer.

POST /tags

http://localhost/tags
Response

Create a new Metapic tag.
A tag can be either an image tag or a text link tag.

Parameters
image_id Id of the image this tag is placed on.
user_id Id of the user this tag belongs to.
x Horizontal position of the tag. The position is a percentage value of the image width so valid values are from 0-1.
y Vertical position of the tag. The position is a percentage value of the image height so valid values are from 0-1.
width The width of the tag. The width is a percentage value of the image width so valid values are from 0-1.
height The height of the tag. The height is a percentage value of the image width so valid values are from 0-1.
link The link url for the tag.
text The text content for the tag.
type Tag type. Valid values are 'text','pricerunner','other'.
created_at Timestamp for when the tag was created.
updated_at Timestamp for when the tag was last updated.

PUT /tags/tag_id

http://localhost/tags/123
Response

Updates a Metapic tag.
Returns the modified tag as a json object.

Parameters
image_id Id of the image this tag is placed on.
user_id Id of the user this tag belongs to.
x Horizontal position of the tag. The position is a percentage value of the image width so valid values are from 0-1.
y Vertical position of the tag. The position is a percentage value of the image height so valid values are from 0-1.
width The width of the tag. The width is a percentage value of the image width so valid values are from 0-1.
height The height of the tag. The height is a percentage value of the image width so valid values are from 0-1.
link The link url for the tag.
text The text content for the tag.
type Tag type. Valid values are 'text','pricerunner','other'.
created_at Timestamp for when the tag was created.
updated_at Timestamp for when the tag was last updated.

DELETE /tags/tag_id

http://localhost/tags/876
Response

Deletes a Metapic tag. Returns the deleted tag as a json object.

Parameters
tag_id Part of the endpoint url. Unsigned integer.

Clicks

The clicks endpoint is used for accessing the number of clicks connected to your client account.

GET /clicks/getAllFromUser

http://localhost/clicks/getAllFromUser

Return the number of clicks connected to that user. Between the from and to dates if not given for all time.

Parameters
user_id The id of the user to fetch clicks for. Unsigned integer.
from Vaild datetime format 2014-11-08 10:24 as string
to Vaild datetime format 2014-11-08 10:24 as string

GET /clicks/getClicksByDate

http://localhost/clicks

You get the number of clicks grouped by date.

Parameters
from Vaild datetime format 2014-11-08 10:24 as string
to Vaild datetime format 2014-11-08 10:24 as string
user_id The id of the user to limit the clicks. Unsigned integer.

News

Metapic news

GET /news

http://localhost/news

Get all news from metapic

How to use our script

You need to have jQyery >1.9 loaded on your page. Import localhost/javascript/iframeScript.js. You can trigger popups from Metapic with help of JQuery events($.event.trigger) with type metapic. You need to call /iframe/generateCode for getting the random code, if the random code is not added the user will be redirected to login. Here is an example how to trigger the search box. 

                        $.event.trigger({
                            type: "metapic",
                            text: editor.selection.getContent(),
                            baseUrl:data['metapicApi'],
                            startPage: "find/default",
                            hideSidebar:true,
                            randomKey:data['random_token']
                        });

EVENT find/default

Triggers the find view and is going to wrap the input text in a a href tag
Response
Parameters
text Text you want wrapped
baseUrl Which server you want to connect to
startPage REQUIREDfind/default
hideSidebar true/false if you want the left sidebar to be hidden
randomKey The random key generated from the endpoint /iframe/genarateCode

EVENT tag-editor

Triggers the tag-editor and is going to return the input div with added data attributes.
Response
Parameters
text REQUIREDThe div you want wrapped as being the taggable area
imgSrc REQUIRED The src to your img
baseUrl Which server you want to connect to
startPage REQUIREDtag-editor
hideSidebar true/false if you want the left sidebar to be hidden
randomKey The random key generated from the endpoint /iframe/genarateCode

EVENT collage

Triggers the collage-editor and is going to return a image with added data attributes.
Response

Parameters
imgSrc The src to a image you want in a collage
baseUrl REQUIREDWhich server you want to connect to
startPage REQUIREDcollage
hideSidebar true/false if you want the left sidebar to be hidden
randomKey The random key generated from the endpoint /iframe/genarateCode