API

L'attribut Api permet de créer facilement des routes d'API REST personnalisées dans WordPress, accessibles via /wp-json.

Utilisation de base

app/Controllers/MyController.php

use Elementum\Attributes\Api;

class MyController extends Controller
    #[Api(
        namespace: 'elementum/v1',
        endpoint: '/hello',
        methods: 'GET',
        params: [
            'name' => 'string',
            'age' => 'number'
        ]
    )]
    public function helloEndpoint($params)
    {
        return [
            'message' => sprintf('Bonjour %s ! Vous avez %d ans.',
                ucfirst($params['name']),
                $params['age']
            )
        ];
    }
}

// URL générée : /wp-json/elementum/v1/hello/Thibault/29
// Les paramètres sont passés dans l'URL, dans l'ordre de leur définition
// Premier paramètre (name) : /Thibault
// Deuxième paramètre (age) : /29

Réponse

La méthode doit retourner un tableau qui sera automatiquement converti en JSON :

{
    "message": "Bonjour Thibault ! Vous avez 29 ans."
}

Paramètres

Paramètres obligatoires

namespace

• Type : string
• Description : Namespace de l'API (première partie de l'URL après /wp-json)
• Exemple : 'elementum/v1'

Paramètres optionnels

endpoint

• Type : string
• Défaut : '/'
• Description : Chemin de l'endpoint (deuxième partie de l'URL après le namespace)

name

• Type : string
• Description : Nom unique identifiant la route
• Remarque : Utile pour les références internes et les filtres

methods

• Type : string|array
• Défaut : 'GET'
• Description : Méthode(s) HTTP acceptée(s)
• Valeurs possibles : 'GET', 'POST', 'PUT', 'DELETE', 'PATCH' ou un tableau de ces valeurs

params

• Type : array
• Défaut : []
• Description : Définition des paramètres attendus et de leur type
• Format : 'nom_parametre' => 'type'
• Types supportés : string, number, boolean, array, object

permission

• Type : boolean
• Défaut : false
• Description : Si true, l'utilisateur doit être authentifié

Exemples avancés

Avec plusieurs méthodes HTTP

#[Api(
    namespace: 'elementum/v1',
    endpoint: '/articles',
    methods: ['GET', 'POST']
)]
public function handleArticles($params, $request)
{
    if ($_SERVER['REQUEST_METHOD'] === 'GET') {
        // Logique pour récupérer les articles
        // Exemple d'URL : /wp-json/elementum/v1/articles
    } else {
        // Exemple d'URL (GET) : /wp-json/elementum/v1/articles
        // Exemple d'URL (POST) : /wp-json/elementum/v1/articles (avec les données dans le corps de la requête)
    }
}

// GET /wp-json/elementum/v1/articles - Récupère la liste des articles
// POST /wp-json/elementum/v1/articles - Crée un nouvel article

Avec validation des paramètres

#[Api(
    namespace: 'elementum/v1',
    endpoint: '/user',
    params: [
        'id' => 'number',
        'email' => 'string',
        'is_admin' => 'boolean'
    ]
)]
public function getUser($params)
{
    // Les paramètres sont automatiquement validés selon les types spécifiés
    return [
        'id' => $params['id'],
        'email' => $params['email'],
        'is_admin' => $params['is_admin']
    ];
}

// URL générée : /wp-json/elementum/v1/user/42/test@example.com/true
// Les paramètres sont passés dans l'ordre de leur définition :
// Premier paramètre (id) : /42
// Deuxième paramètre (email) : /test@example.com
// Troisième paramètre (is_admin) : /true

// Exemple avec cURL (GET) :
// curl https://votresite.com/wp-json/elementum/v1/user/42/test@example.com/true

// Pour les méthodes POST/PUT, les paramètres peuvent aussi être passés dans le corps de la requête :
// curl -X POST https://votresite.com/wp-json/elementum/v1/user \
//   -H 'Content-Type: application/json' \
//   -d '{"id": 42, "email": "test@example.com", "is_admin": true}'

Bonnes pratiques

• Nommage : Utilisez des noms de méthodes descriptifs qui reflètent l'action de l'endpoint
• Documentation : Commentez le but de chaque endpoint et ses paramètres
• Validation : Profitez du système de typage des paramètres pour une validation automatique
• Sécurité : Utilisez le paramètre permission pour protéger les routes sensibles