In order to use the Meride API, it is necessary to provide access credentials to the authorization server, which in response provides the codes to carry out various operations. Operation can be summarized in the following steps

The application sends a request to the authorization server with authorization key
The server in response will provide an access token [obviously the authorization key must be valid]
The application uses this access token in the header of HTTP requests, i.e. the Header, and makes calls to the service of interest.

Receive Authorization key

The authorization key can be found on the Profile page of your Meride account. The first time you need this code you will find a code generation button on this page and activating it will generate a new code that will be immediately displayed on the screen and will remain visible on the page even during successive access.

Once you have this code, you will be asked for an access token by the authorization server at:

http://API_DOMAIN/restauth/v2/verify.json

For example we can make an authorization request with the curl command

curl -i -H "Accept: application/json" -H "auth-code: ZtJaOVJ14NoeaxiT6lBNza9h8XhQBis5C15gNFeOiTSog18cczQCbQKyDRf70x" -H "state: 1234" http://API_DOMAIN/restauth/v2/verify.json

The required Headers are

Accept: currently, only the JSON format is supported, so we will specify application/json
auth-code: the authorization key
state: a random code that limits CSRF attacks. It will be returned in the reply. The same string sent must be returned, otherwise the application should terminate the flow of operations

You will receive an answer similar to this:

{
	"access_token":"abveyCV6uIeo0sDc6TYEa2Z5ssP2OAKPF5j3y5wSDA7ATBDQkskak95DsKw6bz",
	"refresh_token":"H4G5ApRW8le6M7WfNHxXII8Dbfe1cfsNLjzbzhYysbu49SaMqyAY6ns8twvvCN",
	"creation_date":"2012-10-01 18:37:37",
	"expiration_date":null,
	"state":"1234"
}

How to use tokens

The received access_token will be inserted in the HTTP Headers of our API calls, in order to be authorized to receive a response.

For example, if you want to receive information for the embed with ID 40 you can write

curl -i -H "Accept: application/json" -H "access-token: abveyCV6uIeo0sDc6TYEa2Z5ssP2OAKPF5j3y5wSDA7ATBDQkskak95DsKw6bz" http://API_DOMAIN/rest/v2/embed/40.json

1. Example of implementation in PHP

Demonstration implementation of the Meride API using the PHP language.

class Meride_API{
	private $access_token = '';
	private $refresh_token = '';
	private $auth_code = '';
	private $auth_url = 'http://API_DOMAIN/restauth/v2/verify.json';
	private $refresh_url = 'http://API_DOMAIN/restauth/v2/refresh.json';
	
	public function __construct($auth_code)
	{
		$this->auth_code = $auth_code;
		$this->set_tokens();
	}
	
	private function refresh_token()
	{
		$headers = array(
			'Accept: application/json',
			'refresh-token: '.$this->refresh_token,
		);
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_URL, $this->refresh_url);
		
		$content = curl_exec($c);
		curl_close($c);
		$obj = json_decode($content);
        
		if(isset($obj->errors))
		{
			throw new Exception(implode(",", $obj->errors));
		}

		if(!isset($obj->access_token))
		{
			throw new Exception("No access-token");
		}
		else
		{
			$this->access_token = $obj->access_token;
		}
	}
	
	private function generate_state()
	{
		return rand(0, 999999);
	}
	
	private function set_tokens()
	{
		$state = $this->generate_state();
		$headers = array(
			'Accept: application/json',
			'auth-code: '.$this->auth_code,
			'state: '.$state,
		);
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_URL, $this->auth_url);
		
		$content = curl_exec($c);
		curl_close($c);
		$obj = json_decode($content);
		
		if(isset($obj->errors))
		{
			throw new Exception(implode(",", $obj->errors));
		}
		
		if(!isset($obj->state))
		{
			throw new Exception("state not defined");
		}
		else
		{
			if($state != $obj->state)
			{
				throw new Exception("state not equal");
			}
		}
		
		if(!isset($obj->access_token))
		{
			throw new Exception("No access-token");
		}
		else
		{
			$this->access_token = $obj->access_token;
		}
		
		if(isset($obj->expiration_date) and $obj->expiration_date != null and $obj->expiration_date < date('Y-m-d H:i:s'))
		{
			if(isset($obj->refresh_token)){
				$this->refresh_token = $obj->refresh_token;
				$this->refresh_token();
			}
		}
	}
	
	public function get($url, $params = array())
	{
		$headers = array(
			'Accept: application/json', 
			'access-token: '.$this->access_token,
		);
		if(!empty($params)){
			$url = $url . '?' . http_build_query($params);
		}
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_URL, $url);

		$content = curl_exec($c);
		curl_close($c);
		$res = json_decode($content);
		return $res;
    }
    
    public function post($url, $params = array())
	{
		$headers = array(
			'Accept: application/json', 
			'access-token: '.$this->access_token,
		);
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_POST, 1);
		curl_setopt($c, CURLOPT_POSTFIELDS, $params);
		curl_setopt($c, CURLOPT_URL, $url);

		$content = curl_exec($c);
		curl_close($c);
		$res = json_decode($content);
		return $res;
    }
    
    public function put($url, $params = array())
	{
		$headers = array(
			'Accept: application/json', 
			'access-token: '.$this->access_token,
		);
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_CUSTOMREQUEST, "PUT");
		curl_setopt($c, CURLOPT_POSTFIELDS, $params);
		curl_setopt($c, CURLOPT_URL, $url);

		$content = curl_exec($c);
		curl_close($c);
		$res = json_decode($content);
		return $res;
    }
    
    public function delete($url)
	{
		$headers = array(
			'Accept: application/json', 
			'access-token: '.$this->access_token,
		);
		$c = curl_init();
		curl_setopt($c, CURLOPT_RETURNTRANSFER, 1);
		curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
		curl_setopt($c, CURLOPT_CUSTOMREQUEST, "DELETE");
		curl_setopt($c, CURLOPT_URL, $url);

		$content = curl_exec($c);
		curl_close($c);
		$res = json_decode($content);
		return $res;
	}
}

Which you can then use in this way:

$api = new Meride_API("ZtJaOVJ14NoeaxiT6lBNza9h8XhQBis5C15gNFeOiTSog18cczQCbQKyDRf70x");
$response = $api->get("http://API_DOMAIN/rest/v2/embed.json");
echo '<pre>';
print_r($response);
echo '</pre>';