1. Amienscope API
2. Guide de démarrage

Amienscope intègre l'ensemble des événements culturels, sportifs et festifs dans l'agglomération d'Amiens Métropole. Les données de ces événements sont disponibles en OpenData via une API, qui est utilisée notamment pour l'application mobile Amienscope.

Le but de ce document est de fournir aux développeurs d'applications un support de documentation afin d'utiliser efficacement l'API Amienscope.

Les données renvoyées par l'API Amienscope sont au format JSON. Ce format souple et standard permet aux données d'être utilisées dans le cadre de tout type d'application et pour tout type de plateforme.

Le jeu de caractères utilisé par l'API est UTF-8.

Les requêtes sur l'API se font toutes sur un unique sous-domaine spécifique : https://api.amienscope.fr/, via des requêtes HTTP standard.

L'authentification sur l'API Amienscope se fait à l'aide d'une méthode standard (HMAC SHA1), similaire aux processus d'authentification sur des APIs d'envergure (comme par exemple Amazon AWS).

Lorsque vous avez obtenu vos propres codes d'accès à l'API, vous pouvez commencer à effectuer des requêtes. Ces requêtes doivent impérativement comporter des en-têtes (headers HTTP) spécifiques, dont le détail est défini ci-dessous.

Toutes les requêtes HTTP envoyées à l'API doivent impérativement contenir ces quatre en-têtes. Dans le cas contraire, une erreur sera retournée par l'API (cf. Erreurs).

L'UUID du terminal de l'utilisateur peut être envoyé à l'API dans un en-tête supplémentaire, celle-ci facultative.

L'envoi de cette information à l'API permet d'effectuer des statistiques plus précises, et de reconnaître l'utilisateur en lui proposant des contenus personnalisés. Si cela est applicable (dans le cadre d'une application mobile par exemple), nous vous recommandons fortement d'ajouter cet en-tête à vos requêtes.

Chaque requête envoyée à l'API doit être signée, et cette signature jointe aux en-têtes de la requête (dans le champ X-Signature).

La signature s'obtient à l'aide d'un hash HMAC SHA-1 de votre clé privée (ou api_secret, sur 64 caractères), de la date et l'heure courante (envoyés dans le champ X-Datetime), et la chaîne à signer (string to sign) constituée du verbe, de l'URI, et de la date et heure.

STRING_TO_SIGN = VERB + URI + DATETIME

X-Signature = HMAC_SHA1 ( STRING_TO_SIGN , API_SECRET )

$x_public_key = 'rbp6e535XxUhb069fkLX6hThqK8tyMSh'; /* Your Public Key */
$api_secret   = '2NgDm6WbhWTSPtZv2vU4GnxzevqHySatz3AGHzP76Sd6yB7A9UrXq5f6kRB5ddEX'; /* Your Private Key (API Secret) */
$email_addr   = 'john.doe@example.com'; /* Your account e-mail */

$verb         = 'GET'; /* The HTTP Method (verb) of your API request */
$request_uri  = '/get/categories'; /* The URI of your API request */

$datetime     = time(); /* Current time and date (Can be UNIX timestamp or any DateTime date format) */

/* The string to sign, used for signing the request. */
/* In this example, it will be : « GET/get/categories1234567890 » */
$str_to_sign  = $verb . $request_uri . $datetime ;

/* Generating the signature with a HMAC Hash (SHA-1) */
$x_signature  = hash_hmac('sha1', $str_to_sign , $api_secret );

$api_connection = curl_init();
				
curl_setopt_array($api_connection, array(
	CURLOPT_RETURNTRANSFER	=> TRUE,
	CURLOPT_USERAGENT	=> 'My Awesome Application', /* Setting a recognizable User-Agent is recommended */
	CURLOPT_URL		=> 'https://api.amienscope.fr'. $request_uri ,
	CURLOPT_HTTPHEADER	=> array(
		/* HTTP Headers to send */
		'X-Public-Key:'. $x_public_key ,
		'X-Datetime:'. $datetime ,
		'X-Signature:'. $x_signature ,
		'email_addr:'. $email_addr 
	)
));

$result = curl_exec($api_connection);
echo $result ;

Vous êtes maintenant prêt(e) à effectuer des requêtes sur l'API Amienscope.

Si vous rencontrez des difficultés à utiliser vos codes d'accès API dans le cadre de votre développement, notre équipe technique est là pour répondre à vos questions.

Pour la suite, nous vous invitons à consulter le chapitre Manipulation d'événements.