Slideshow Copy API

This service exposes two endpoints to copy slideshows between locales using JWT authentication. Slideshows can be copied from one WordPress site to another, preserving slide content and structure.

Overview

The slideshow copy functionality allows content editors to replicate slideshow posts from one locale to another. This is particularly useful for translating and localizing content across the Aleteia network.

Endpoints

Create Copy Request

Initiates a slideshow copy operation from one locale to another.

POST /slideshows.json

Request Body

{
  "copy_request": {
    "url": "source slideshow URL",
    "locale": "destination locale"
  }
}

Example Request

{
  "copy_request": {
    "url": "https://fr.aleteia.org/slideshow/lamour-vrai-est-la-vraie-liberte/",
    "locale": "en"
  }
}

Authentication

The endpoint requires JWT authentication. The JWT payload must contain the request parameters:

$payload = array(
  'url' => 'https://fr.aleteia.org/slideshow/lamour-vrai-est-la-vraie-liberte/',
  'locale' => 'en',
);

Include the token in the Authorization header:

Authorization: Bearer <JWT_TOKEN>

Response

Returns the created copy request or a JSON error message (validation/auth errors). The response includes an id field used to query the status.

Success Response (201 Created):

{
  "id": 1,
  "url": "https://fr.aleteia.org/slideshow/lamour-vrai-est-la-vraie-liberte/",
  "locale": "en",
  "aasm_state": "created",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Error Response (422 Unprocessable Entity):

{
  "errors": {
    "url": ["is invalid"],
    "locale": ["is not included in the list"]
  }
}

Check Copy Status

Query the status of a previously created copy request.

GET /slideshows/:id.json

Authentication

JWT payload must contain the request ID:

{ "id": 1 }

Example Response

{
  "id": 1,
  "url": "https://fr.aleteia.org/slideshow/lamour-vrai-est-la-vraie-liberte/",
  "locale": "en",
  "aasm_state": "copied",
  "target_url": "https://aleteia.org/slideshow/true-love-is-true-freedom/",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Job States

The copy request transitions through several states during processing:

State	Description
created	Request received and waiting to be processed
copied	Slideshow copied successfully to target locale
partially_copied	Copied with some slides missing in target locale
retryable	Temporary failure; scheduled for automatic retry
errored	Permanent failure; requires manual intervention

In typical conditions, most jobs complete in 2–3 seconds.

Copy Process Flow

The following sequence diagram illustrates the complete slideshow copy process:

Error Handling

Common Errors

Error	HTTP Status	Description
Invalid URL	422	Source URL format is invalid
Invalid locale	422	Target locale not supported
Slideshow not found	422	Source slideshow doesn't exist
Authentication failed	401	JWT token invalid or expired
Rate limited	429	Too many requests

Retry Logic

For temporary failures (network issues, API timeouts), the system automatically retries with exponential backoff:

1. First retry: 30 seconds
2. Second retry: 2 minutes
3. Third retry: 10 minutes
4. After 3 failed retries: marked as errored

Integration with Media Copy

When copying a slideshow, the system leverages the media copy functionality to handle images:

1. Each slide image is processed through the standard media copy pipeline
2. Images are de-duplicated using file hash comparison
3. Existing copied images are reused if available

Available Locales

Slideshows can be copied between any of the supported locales:

Locale	Site
en	aleteia.org
es	es.aleteia.org
fr	fr.aleteia.org
it	it.aleteia.org
pt	pt.aleteia.org
pl	pl.aleteia.org
ar	ar.aleteia.org
si	si.aleteia.org

Example Usage

PHP Client Example

<?php
// Create JWT token
$secret = getenv('JWT_SECRET');
$payload = [
    'url' => 'https://fr.aleteia.org/slideshow/example/',
    'locale' => 'en',
    'exp' => time() + 300 // 5 minute expiration
];
$token = \Firebase\JWT\JWT::encode($payload, $secret, 'HS256');

// Make API request
$client = new \GuzzleHttp\Client();
$response = $client->post('https://api.example.com/slideshows.json', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token,
        'Content-Type' => 'application/json'
    ],
    'json' => [
        'copy_request' => [
            'url' => 'https://fr.aleteia.org/slideshow/example/',
            'locale' => 'en'
        ]
    ]
]);

$result = json_decode($response->getBody(), true);
$requestId = $result['id'];

// Poll for completion
do {
    sleep(1);
    $statusToken = \Firebase\JWT\JWT::encode(['id' => $requestId], $secret, 'HS256');
    $statusResponse = $client->get("https://api.example.com/slideshows/{$requestId}.json", [
        'headers' => ['Authorization' => 'Bearer ' . $statusToken]
    ]);
    $status = json_decode($statusResponse->getBody(), true);
} while ($status['aasm_state'] === 'created');

echo "Copy completed with status: " . $status['aasm_state'];

cURL Example

# Create copy request
curl -X POST https://api.example.com/slideshows.json \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "copy_request": {
      "url": "https://fr.aleteia.org/slideshow/example/",
      "locale": "en"
    }
  }'

# Check status
curl https://api.example.com/slideshows/1.json \
  -H "Authorization: Bearer $JWT_TOKEN"