API Compte client

Introduction

Open Street est un service d’optimisation d’itinéraires multipoints qui est accessible aux développeurs qui souhaitent inclure cette technologie dans leurs propres applications. Le service peut être consommé soit sous la forme d’un forfait qui donne droit à des quotas d’optimisations par jour (exemple : 30 optimisations par jour de 50 points chacune), ou bien en tarification à l’usage, c’est à dire que chaque optimisation est décomptée du compte utilisateur jusqu’à épuisement de ce dernier.

C’est pour ce second cas de figure qu’il existe une API de gestion de compte utilisateur. Cette API permet de créer des comptes d’optimisation, et de suivre leur consommation.

Description de l’API de compte client

Protocole utilisé

Comme toutes les API du service Open Street, le protocole HTTP 1.1 est utilisé, et deux méthodes sont nécessaire pour couvrir toutes les fonctionnalités de cette API : POST et GET. Il y a toujours au moins un paramètre d’URL dans la requête, même dans le cas de méthodes POST.

Cette API d’optimisation n’est pas susceptible de recevoir de caractères spéciaux ou accentués, mais les URL doivent tout de même être correctement encodées. Les navigateurs récents encodent automatiquement les URL mais pas toujours les librairies HTTP. Avec le langage PHP on poura utiliser urlencode() .

Toutes nos API supportent la compression gzip, il est donc fortement conseillé d’activer cette fonctionnalité dans votre client HTTP. Pour vérifier que la compression est active, l’en-tête de la requête du client doit comporter Accept-Encoding : "gzip, deflate"  et l’en-tête de la réponse du serveur doit comporter Content-Encoding : "gzip" .

Le temps de traitement des requêtes est court à l’échelle d’une interface utilisateur, généralement inférieur à 300 ms.

Catalogue des paramètres d’entrée

Cette API accepte plusieurs types de requêtes, qui produisent des résultats différents. On distinguera les paramètres dits « parents » qui déterminent le type de requête, et les paramètres dits « enfants » qui sont nécessaires au bon fonctionnement de la requête. Les paramètres parents n’attenent pas qu’une valeur leur soit affectée, seule leur précence suffit. Les paramètres enfants doivent par contre comporter une valeur associée, avec une requête de type soit POST, soit GET.

Une astérisque* indique un paramètre obligatoire pour lancer un calcul.

Sur l’infrastructure Open Street, il existe deux types de comptes : le compte client qui contient les données de facturation (coordonnées, tarif applicable) ainsi que le compte de calcul qui est affecté à un compte client. Ce compte de calcul permet d’effectuer des optimisations d’itinéraires sans avoir besoin de s’authentifier auprès du compte client.

Un compte client est défini par son identifiant (email) et son mot de passe, tandis qu’un compte de calcul est défini par sa clé de 32 caractères (paramètre key ci-après).

La plupart du temps, un client possèdera un seul compte de calcul. Mais un client peut s’il le souhaite ouvrir plusieurs comptes de calcul, qui peuvent être utiles notamment à des fins de statistiques. Dans ce cas, plusieurs comptes de calcul seront à même de débiter le compte client.

Paramètre parent	Paramètres enfants	Explication	Méthode
deposits	key*	Liste des dépôts de crédit effectués par le client qui possède ce compte de calcul.	GET
credit	key*	Valeur du crédit restant sur le compte client qui possède ce compte de calcul.	GET
tsp_requests	key*, date	Liste des requêtes effectuées par le compte de calcul spécifié. Le paramètre date indique une date de début sous la forme YYYYMMDD.	GET
tsp_rates	key*	Grille tarifaire applicable pour ce compte de calcul.	GET
tsp_quotas	key*	Quotas applicables pour le client qui possède ce compte de calcul.	GET
create_key	name*, description, email*	Crée un compte de calcul affecté au compte client spécifié grâce à l’email.	GET
create_customer	address_company*, address_person*, address_street*, address_street2, address_pc*, address_city*, address_cedex, email*, password_hashed_db*	Crée un compte client avec ses coordonnées, son identifiant (email) et le hash MD5 de son mot de passe.	POST
salt	null	Renvoie une valeur de 32 caractères qui change chaque minute, et qui est utile au processus d’authentification pour la requête query_customer.	GET
query_customer	email*, password_hashed_js*	Liste des comptes de calcul affectés au compte client. Cette requête est sensible. Le paramètre password_hashed_js est calculé par md5(md5($password_typed).$salt) (syntaxe PHP).	POST

Méthodes d’authentification

Pour ces différentes requêtes, on distingue différents types d’authentification selon la requête.

• La plupart du temps, une clé de compte de calcul est suffisante pour effectuer une requête. Cette clé doit être gardée absolument confidentielle. De par sa longueur de 32 caractères, une personne mal intentionnée aurait une chance sur 1,53 10⁵⁴ de découvrir votre clé ce qui semble être un risque acceptable.
• Pour créer un compte client, un identifiant (adresse email) et un mot de passe sont requis. Le mot de passe doit être hashé en md5 et non pas transmis en clair lors de la création du compte.
• Pour interroger un compte client et lister ses comptes de calcul, un processus d’authentification plus compliqué est requis. Le mot de passe n’est jamais transmis en clair ni simplement hashé. Le paramètre password_hashed_js doit être md5(md5($password_typed).$salt), ou dit autrement, le hash md5 de : hash md5 du mot de passe saisi, concaténé à la valeur salt obtenue à partir de la requête du même nom. Cette sécurité accrue est définie pour protéger les valeurs de clés.

Utilisation des données

Exemples

Pour exemple, la requête credit est de type GET, on passera donc tous ses paramètres en paramètres d’URL. La requête complète va donc être : https://maps.open-street.com/api/account/?credit&key=cle-compte-calcul .

Le résultat suivant indique qu’il reste 95,44 € sur le compte client interrogé.

La requête create_customer est de type POST, donc on passera le paramètre parent en paramètre d’URL, et tous les autres paramètres seront de type POST. La méthode HTTP employée est POST. Voici un script bash qui créer une requête de ce type. On pourra également utiliser javascript pour créer une telle requête (jQuery recommandé) ou un simple formulaire HTML synchrone.

Le résultat sera sobrement :

Conseils d’utilisation

Lorsque vous traitez cet objet json, vous devez impérativement récupérer les valeurs grâce à leur chaîne associée, et non pas par leur position dans le document ou leur numéro de ligne. En effet, d’autres données sont susceptibles de s’intercaler à l’avenir et c’est le seul moyen de respecter la compatibilité.

Le résultat de la requête doit être testé notamment avec le code de status. S’il indique autre chose que « OK » alors la requête aura échoué. Les codes d’erreurs qui suivent sont susceptibles d’évoluer.

Codes d’erreur

Voici la signification des codes d’erreur que l’on peut rencontrer avec cette API.

Code	Explication
SYNTAX_ERROR	La requête est incomplète ou comporte une erreur.
REQUEST_TOO_LONG	Les paramètres GET et POST sont beaucoup trop longs.
WRONG_KEY	Votre clé d’authentification est fausse.
TOO_MANY_PARENT_PARAMETERS	Vous avez tenté deux paramètres parents dans une même requête alors que le paramètre parent est unique et définit le type de la requête.
MISSING_CHILD_PARAMETER	Vous n’avez pas renseigné tous les paramètres requis pour cette requête.
MISSING_PARAMETER	Vous n’avez pas renseigné de paramètre.
UNKNOWN_PARAMETER	Un des paramètres est inconnu.
WRONG_METHOD	Vous n’avez pas utilisé la bonne méthode HTTP entre POST et GET.
WRONG_ADDRESS	Un des champs d’adresse est trop long (limite à 255 caractères par champ sauf address_pc à 10 et address_cedex à 20).
WRONG_EMAIL	L’email est invalide.
WRONG_PASSWORD	Le mot de passe est invalide.