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/verify

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/verify

Gli Headers richiesti sono

Accept: ora è supportato soltanto il formato JSON, quindi si specificherà application/json
auth-code: l'authorization key
state: un codice casuale che limita gli attacchi di tipo CSRF. Verrà restituito nella risposta. Deve essere restituita la stessa stringa inviata, altrimenti l'applicazione dovrebbe terminare il flusso delle operazioni

You will receive an answer similar to this:

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

How to use tokens

L'access_token ricevuto sarà inserito negli Headers HTTP delle nostre chiamate alle API, in modo da essere autorizzati a ricevere una risposta.

Ad esempio se si vuole ricevere le informazioni per l'embed con ID 40 si scriverà

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

1. Example of implementation in PHP

Implementazione dimostrativa delle API di Meride utilizzando il linguaggio PHP.

class Meride_API{
	private $access_token = '';
	private $refresh_token = '';
	private $auth_code = '';
	private $auth_url = 'http://API_DOMAIN/restauth/verify';
	
	public function __construct($auth_code)
	{
		$this->auth_code = $auth_code;
		$this->set_tokens();
	}
	
	private function valid_token()
	{
		// se c'è bisogno di generarne uno nuovo dopo la scadenza
		return true;
	}
	
	private function refresh_token()
	{
		// richiede un nuovo auth token utilizzando il refresh_token
	}
	
	private function generate_state()
	{
		return rand(0, 999999);
	}
	
	private function set_tokens()
	{
		if(!empty($this->refresh_token) and !empty($this->access_token))
		{
			if(!$this->valid_token())
			{
				$this->refresh_token;
			}
		}
		$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->refresh_token))
		{
			$this->refresh_token = $obj->refresh_token;
		}
		
	}
	
	public function request($url, $headers = array(), $params = array())
	{
		$headers = array(
			'Accept: application/json', 
			'Content-Type: 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_URL, $url);
		
		$content = curl_exec($c);
		curl_close($c);
		$res = json_decode($content);
		return $res;
	}
}

Che posso poi utilizzare in questo modo:

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