Spécification Api Joomla

From Joomla! Documentation

This page is a translated version of the page Joomla Api Specification and the translation is 50% complete.

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎français • ‎italiano
Joomla! 
4.0

Cette page est destinée à refléter la spécification de l'API Joomla. Ceci sera mis à jour et reflétera la dernière version de Joomla à tout moment

Authentification

Il existe un groupe de plugins api-authentication pour autoriser 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 ; cependant il nous avons l'intention que cela puisse être accompli avec le groupe de plugin (en désactivant le plugin "API Authentication - Joomla Token" et le plugin "User - Joomla Token"). La construction de l'authentification utilise une implémentation "Bearer Token".

The hmac is the main security feature of our Bearer token implementation. This is the RFC 2104 HMAC of the seed data using Joomla's site secret (the $secret in configuration.php) as the key. The base64 encoded seed is stored in the database in the user profile table of the database.

The token itself is the base64-encoded representation of a string algorithm:user_id:hmac. The algorithm tells us which cryptographic hash function was used to generate the HMAC. Per the security considerations of RFC 6151 we forbid the use of the less secure cryptographic hash functions. In fact, the current implementation only allows SHA-256 and SHA-512 with SHA-256 being the (hardcoded) method used to generate the token displayed to the user. (i.e. SHA-512 is added for forward compatibility).

For security and privacy reasons users can only view their own token, even if they are Super Users. Users with com_users edit privileges can also disable, enable or reset another user's token (if they believe the token has been compromised) BUT they still cannot view it. Users can also choose to disable their own API Key.

There is also a legacy basic authentication plugin for simple local development however this is likely to be removed before the release of Joomla 4.0.0 stable.


Requêtes

Négociation de Contenu

Par défaut, Joomla renverra les réponses de l'API JSON lorsque demandé avec un en-tête Accepts: application/json, ainsi qu'avec l'en-tête spécifique de l'API JSON. Joomla prendra en charge la possibilité d’ajouter des types de contenu supplémentaires pouvant faire l’objet d’une réponse. Les plug-ins système ajoutant ce mappage seront chargés de s'assurer que les composants prennent en charge ce mappage. Le coeur de Joomla ne supportera pas 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

Basic Basiques

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 réside dans le dossier api de Joomla, toutes les routes commencent par /api sur l'URL racine de Joomla. Ceci n'est personnalisable que si vous décidez de réécrire les emplacements des dossiers avec des fichiers includes/define.php personnalisés à tous les niveaux du CMS (faites-le entièrement à vos risques et périls et n'attendez pas beaucoup de, voir aucun support !)


Ajouter des Routes

Routes are registered through plugins with type webservice. A plugin can add one or more routes (each should be aware of it's RESTful type). Whilst puristically 1 plugin per content type would be better, there is also a tradeoff between number of plugins installed on your Joomla site for management. Therefore we recommend a plugin per component to expose admin data and then if you are coding in extra routes an extra plugin (of course this is just a recommendation - use cases of course vary!)

Réponses

Format Réponse API

Joomla evaluated several response API Formats including JSON-LD, JSON API and Collection+JSON. For a more detailed evaluation you can look at this summary document produced as part of our GSOC 2017 project. We have settled on using the JSON API v1.0 specification (at the time of producing the JSON API 1.1 which recently became release candidate had no major libraries implementing it and appeared stuck).

The JSON API v1.0 specification can be found on the json api website.

Some batch interactions in the Joomla API will also use the JSON API Partial Success module for error handling which can be found in this gist.


Richardson Maturity Model and Hypermedia

We expect Joomla to largely comply with Level 3 of the Richardson Maturity Model. If you want to read about what this means we recommend looking at the Fowler page on it. Our entity systems (JTable and JModel) aren't ideally suited for this which means in some places especially around data relations there's likely to be some implementation difficulties.