Basic Requests

This page shows basic examples for working with the Joomla Webservices API.

Setup

First we need to set up our base variables:

<?php
$baseUrl = 'https://yoursite.com/api/index.php/v1';
$token = 'YOUR_API_TOKEN';

$headers = [
    'X-Joomla-Token: ' . $token,
    'Content-Type: application/json'
];
?>

GET Request - Retrieve articles

<?php
function getArticles() {
    global $baseUrl, $headers;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '/content/articles');
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        return json_decode($response, true);
    }

    return null;
}

// Usage
$articles = getArticles();
foreach ($articles['data'] as $article) {
    echo $article['attributes']['title'] . "\n";
}
?>

POST Request - Create article

<?php
function createArticle($title, $intro, $fulltext, $categoryId = 2) {
    global $baseUrl, $headers;

    $data = [
        'title' => $title,
        'alias' => str_replace(' ', '-', strtolower($title)),
        'introtext' => $intro,
        'fulltext' => $fulltext,
        'catid' => $categoryId,
        'state' => 1,
        'access' => 1,
        'language' => '*'
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '/content/articles');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 201) {
        return json_decode($response, true);
    }

    throw new Exception('Error creating article: ' . $response);
}

// Usage
$newArticle = createArticle(
    'My New Article',
    'This is the introduction',
    'This is the full text of the article'
);
echo "Article created with ID: " . $newArticle['data']['id'];
?>

PATCH Request - Update article

<?php
function updateArticle($articleId, $updates) {
    global $baseUrl, $headers;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '/content/articles/' . $articleId);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($updates));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return $httpCode === 200;
}

// Usage
$updated = updateArticle(1, [
    'title' => 'Updated Title',
    'state' => 1
]);

if ($updated) {
    echo "Article successfully updated";
}
?>

DELETE Request - Delete article

<?php
function deleteArticle($articleId) {
    global $baseUrl, $headers;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . '/content/articles/' . $articleId);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return $httpCode === 204;
}

// Usage
$deleted = deleteArticle(1);
if ($deleted) {
    echo "Article successfully deleted";
}
?>

Error Handling

Always add error handling to your requests:

<?php
function makeApiRequest($method, $endpoint, $data = null) {
    global $baseUrl, $headers;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    if ($method !== 'GET') {
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        if ($data !== null) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }
    }

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    curl_close($ch);

    if ($error) {
        throw new Exception('CURL Error: ' . $error);
    }

    if ($httpCode >= 400) {
        $errorData = json_decode($response, true);
        $errorMessage = $errorData['errors'][0]['detail'] ?? 'Unknown error';
        throw new Exception("API Error ($httpCode): $errorMessage");
    }

    return json_decode($response, true);
}

// Usage
try {
    $articles = makeApiRequest('GET', '/content/articles');
    print_r($articles);
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}
?>

JavaScript Fetch Example

For frontend applications:

const API_BASE = 'https://yoursite.com/api/index.php/v1';
const API_TOKEN = 'YOUR_API_TOKEN';

async function getArticles() {
    try {
        const response = await fetch(`${API_BASE}/content/articles`, {
            method: 'GET',
            headers: {
                'X-Joomla-Token': API_TOKEN,
                'Content-Type': 'application/json'
            }
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error fetching articles:', error);
        return null;
    }
}

// Usage
getArticles().then(articles => {
    if (articles && articles.data) {
        articles.data.forEach(article => {
            console.log(article.attributes.title);
        });
    }
});