Politique des APIs Mandriva

De Wiki de la communauté Mandriva.

Cette page est une ébauche. Elle mérite des améliorations.
Si vous voulez contribuer, cliquez simplement sur l'onglet modifier. Consultez également les autres pages dont le contenu est à réviser.

À noter !
Chaque API est expliquée ici avec une URL de référence http://api.mandriva.com/{nom-de-api}/ . Bien sur, il se peut que nous ayons besoin de répartir les API sur différents serveurs de base (comme http://a.mandriva.com/api/ pour les produits, etc.). Cela sera décidé plus tard.

Versioning

Chaque API doit présenter une version d'API (http://api.mandriva.com/{nom-de-api}/{version-api}/). Chaque version peut supporter des révisions, mais celles-ci doivent être rétro-compatibles. En cas d'une augmentation de version, la version N-1 d'une API DOIT être supportée, N-i (i > 1) PEUT être supportée.

Codage des données

Chaque API DOIT considérer que les données d'entrée sont codées en UTF-8, et DOIVENT produire des données codées en UTF-8.

Protocoles

Chaque API devrait partager le même protocole de référence. Le(s) protocole(s) des API n'est pas encore complètement décidé.

Une REST API DOIT au moins donner une réponse dans les formats de retour suivants :

• xml (comme format par défaut) ; le format détaillé de xml est dépendant de l'API ;
• json (voir http://json.org/ );
• wddx (voir http://www.openwddx.org/ ).

Elle PEUT fournir aussi d'autres formats de retour (serialisé PHP, RDF, RSS, CSV, autres ), suivant son utilisation. Si le service utilisateur désire un format particulier, il DOIT le dire en utilisant un paramètre au format GET (http://api/method?format=rdf).

Pour les requêtes POST, le format d'entrée pour les REST API DOIT être du XML valide, codé en UTF-8.

Discussion:

• SOAP est agréable, relativement plus facile/rapide que REST, mais lourd, et non compatible avec une sortie en clair ;
• les deux (REST/SOAP) peuvent être difficiles à utiliser (besoin de trouver une méthode pour unifier le code de répartition) ;
• un schéma XML Mandriva unifié devrait être défini, pour toutes les API. Ou plusieurs schémas, par API/espace de nommage.

Autre solution à étudier : le protocole GData (http://code.google.com/apis/gdata/protocol.html ).

Documentation

Chaque API DOIT avoir un document publiant ses méthodes, les formats d'entrée et de sortie des données

Identification des ressources (redirections)

Pour chaque API, certains constituants PEUVENT avoir des alias d'identificateurs permanents pour les méthodes GET/HEAD (qui DOIT alors rediriger vers le bon par un code de retour HTTP 301), de la forme http://api.mandriva.com/{nom-api}/{version-api}/{simple-unique-id}. Notez que si vous dépréciez un identificateur, vous DEVEZ utiliser ce mécanisme afin que le client sache où rechercher la bonne ressource. Toute autre méthode HTTP (PUT, POST, DELETE) DOIT utiliser l'identificateur permanent.

Les identificateurs permanents (ou leurs aliases) DEVRAIENT être utilisés par tout système mandriva pour référer à l'objet en cours. C'est à dire par exemple :

• quand le Store réfère à un produit Mandriva donné (disons, Discovery 2006.0 pour x86_64), il devrait y référer, (NdT ??? sur le serveur principal) , avec l'identificateur API du produit
• quand Expert réfère à un type de support donné, il devrait utiliser les identificateurs API du produit, le support, (NdT ??? du coté du serveur) ;
• et ainsi de suite

Ceci doit être encore travaillé : des identificateurs tout à fait identiques devraient être utilisés sur tous les services en ligne, et si possible, également au sein du système de distribution.

Clé utilisateur des API

Chaque API PEUT demander une clé API pour être utilisé. L'avantage à utiliser une telle clé est de suivre l'usage des ressources. Si utilisée, une clé DOIT être personnelle et unique. Toute utilisation abusive DEVRAIT déclencher la révocation de la clé.

(NdT ??? Sur le serveur ), la clé DOIT être attachée au compte utilisateur Mandriva.

(a)synchronisme

Pour les premières versions, les API sont supposés être synchrones (c'est à dire, vous demandez quelque-chose, vous avez la réponse en même temps). Une spécification ultérieure définira si/comment certaines peuvent être asynchrones (vous demandez quelque-chose et continuez votre travail, le serveur voous répondra plus tard à l'endroit convenu).