Joomla! Documentation™

Joomla! 

4.0

Cette page est destinée à refléter les spécifications de l'API des services Web API de Joomla. Elle sera mise à jour et reflétera la dernière version de Joomla à tout moment.

Authentification

Il existe un groupe de plugins api-authentication pour permettre une authentification personnalisée au noyau de Joomla qui peut avoir n'importe quelle implémentation. Nous avons choisi de ne pas implémenter les spécifications complètes de oAuth 2 dans le cœur ; mais il est prévu que cela puisse être réalisé avec le groupe de plugins (et en désactivant le plugin "API Authentication - Joomla Token" et le plugin "User - Joomla Token"). L'authentification intégrée utilise une implémentation de "Bearer Token".

Le hmac est la principale caractéristique de sécurité de notre implémentation deBearer token. Il s'agit du RFC 2104 HMAC des données de la graine en clé en utilisant le secret du site de Joomla (le $secret dans configuration.php) comme clé. La clé encodée en base64 est stockée dans la base de données dans la table du profil de l'utilisateur de la base de données.

Le jeton lui-même est la représentation codée en base64 d'une chaîne algorithme:user_id:hmac. L'algorithme nous indique quelle fonction de hachage cryptographique a été utilisée pour générer le HMAC. Conformément aux considérations de sécurité de RFC 6151, nous interdisons l'utilisation des fonctions de hachage cryptographiques les moins sûres. En fait, l'implémentation actuelle n'autorise que SHA-256 et SHA-512, SHA-256 étant la méthode (codée en dur) utilisée pour générer le jeton affiché à l'utilisateur. (c'est-à-dire que SHA-512 est ajouté pour la compatibilité future).

Pour des raisons de sécurité et de confidentialité, les utilisateurs ne peuvent voir que leur propre jeton, même s'ils sont Super Utilisateurs. Les utilisateurs disposant des privilèges de modification com_users peuvent également désactiver, activer ou réinitialiser le jeton d'un autre utilisateur (s'ils pensent que le jeton a été compromis) MAIS ils ne peuvent toujours pas le visualiser. Les utilisateurs peuvent également choisir de désactiver leur propre clé API.

Il existe également un ancien plugin d'authentification de base pour le développement local simple, mais il est probable qu'il sera supprimé avant la sortie de la version stable de Joomla 4.0.0.

Requêtes

Négociation de Contenu

Par défaut, Joomla renvoie les réponses API JSON lorsqu'elles sont demandées avec un en-tête Accept : application/json ainsi qu'avec l'en-tête API JSON spécifique. Joomla prendra en charge la possibilité d'ajouter des types de contenu supplémentaires pouvant faire l'objet d'une réponse. Les plugins système ajoutant ce mappage seront responsables de s'assurer que les composants supportent ce mappage. Le noyau de Joomla ne prendra pas en charge les types de contenu supplémentaires.

Négociation de Langage

Actuellement, la négociation de langue n'est pas prise en charge. Cependant, nous sommes prêts à ajouter un support pour cela à l'avenir.

Routage

Informations de base

Joomla CMS doit utiliser un routeur distinct pour l'API, car l'API sera strictement RESTful (c'est-à-dire qu'une demande POST et GET adressée à la même URL donnera des résultats différents). Pour cela, nous allons donc utiliser le routeur Joomla Framework déjà RESTful, puis mapper les requêtes sur les variables JInput afin que des données JInput similaires soient renseignées sur celles des interfaces Web Joomla.

Comme l'API de Joomla est installée dans le répertoire api de Joomla, toutes les connexions commencent par /api sur l'URL racine de Joomla. Ceci n'est pas personnalisable, à moins que vous ne décidiez de réécrire les emplacements des dossiers avec des fichiers includes/defines.php personnalisés à tous les niveaux du système (faites-le entièrement à vos risques et périls et n'attendez pas beaucoup/tout soutien !)

Ajouter des Routes

Les connexions sont enregistrées par les plugins avec le type webservice. Un plugin peut ajouter une ou plusieurs connexions (chacune doit être consciente de son type RESTful). Si, d'un point de vue puriste, un plugin par type de contenu serait préférable, il y a également un compromis entre le nombre de plugins installés sur votre site Joomla pour la gestion. Par conséquent, nous recommandons un plugin par composant pour accéder aux données d'administration et, si vous codifiez des routages supplémentaires, un plugin supplémentaire (bien sûr, ce n'est qu'une recommandation - les cas d'utilisation varient bien sûr !)

Réponses

Format Réponse API

Joomla a évalué plusieurs formats d'API de réponse, notamment JSON-LD, JSON API et Collection+JSON. Pour une évaluation plus détaillée, vous pouvez consulter ce document de synthèse produit dans le cadre de notre projet GSOC 2017. Nous avons décidé d'utiliser la spécification JSON API v1.0 (au moment de la production de la JSON API 1.1, qui est récemment devenue une version candidate, aucune bibliothèque majeure ne l'implémentait et elle semblait bloquée).

La spécification de l'API JSON v1.0 peut être consultée sur le site de l'api json.

Certaines interactions par lots dans l'API Joomla utiliseront également le module JSON API partiellement réussi pour la gestion des erreurs, qui peut être trouvé dans ce gist.

Modèle de maturité de Richardson et hypermédia

Nous nous attendons à ce que Joomla soit largement conforme au niveau 3 du modèle de maturité de Richardson. Si vous voulez lire ce que cela signifie, nous vous recommandons de consulter la page de Martin Fowler à ce sujet. Nos systèmes d'entités (JTable et JModel) ne sont pas idéalement adaptés à cela, ce qui signifie qu'à certains endroits, en particulier autour des relations de données, il y aura probablement quelques difficultés de mise en œuvre.