Homepage Slides

8 vues Markdown

The eight endpoints for the homepage slider, its images and its videos.

Overview

Slides feed the rotating area at the top of the homepage. Every slide has a main image, and that image is required; the texts, the link and the video are not.

Texts are kept per language: title, description and link live separately in each. Leave the text out in one language and the slide quietly shows there as image alone.

The image and the video have endpoints of their own. The image is always there, while the video is an optional layer, and removing it leaves the slide back on its image.

Reference

Listing the Slides

get/api/v1/admin/website/slides
Website/GetSlides admin

Returns the slides in the homepage slider.

Query 3
searchstringSearches the titles.
pageintWhich page.
limitintRecords per page. A hundred at most.
Response fields data[] — 4 + meta — 4
idintThe slide id.
titlestringIts title in the current language.
linkstringIts link in the current language.
created_atstringWhen it was created.
totalintHow many slides there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/website/slides' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.example.com/api/v1/admin/website/slides', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The list carries NO STATUS and NO RANK: read the detail to see which slide is live.
$slides = Api::Website()->GetSlides()['data'];

Reading One Slide

get/api/v1/admin/website/slides/{id}
Website/GetSlide admin

Returns one slide with its texts, image and video.

Response fields data — 7
idintThe slide id.
statusstringWhether the slide is live.
rankintWhere it sits in the slider.
created_atstring | nullWhen it was created.
languagesobjectThe title, description and link per language.
imagestring | nullThe main image address.
videoobject | nullThe video: its address and length. Empty when no video was set.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request 
curl 'https://panel.example.com/api/v1/admin/website/slides/2' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The video field can come back EMPTY, so check it exists before reading.
$slide = Api::Website()->GetSlide(['id' => $id])['data'];
$clip  = $slide['video']['url'] ?? null;

Creating a Slide

post/api/v1/admin/website/slides
Website/CreateSlide admin the image is required

Adds a new slide to the homepage slider.

Body 4
imagestringreqThe slide's main image. A slide cannot be created without one.
statusstringWhether the slide is live. Live by default.
rankintWhere it sits in the slider.
languagesobjectThe title, description and link per language. None of the texts is required.
Response fields 201 — data — 7
dataobjectThe slide created. Same shape as the detail endpoint.
Errors 3
image_required422No main image was sent.
create_failed500The slide could not be created.
insufficient_scope403The key lacks the required scope.
Request 
curl -X POST 'https://panel.example.com/api/v1/admin/website/slides' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"image":"https://ornek.com/slayt.jpg","languages":{"tr":{"title":"Hos geldiniz"}}}'
const res = await fetch('https://panel.example.com/api/v1/admin/website/slides', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image: 'https://example.com/slide.jpg',
    languages: { en: { title: 'Welcome', link: 'https://example.com/' } },
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'image'     => 'https://example.com/slide.jpg',
        'languages' => ['en' => ['title' => 'Welcome', 'link' => 'https://example.com/']],
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// A slide is born LIVE and reaches the homepage at once; send it off while preparing.
Api::Website()->CreateSlide([
    'image'  => $data,
    'status' => 'inactive',
]);

Updating a Slide

patch/api/v1/admin/website/slides/{id}
Website/UpdateSlide admin

Changes a slide's status, its place and its texts.

Body 4
statusstringWhether the slide is live.
rankintWhere it sits in the slider.
languagesobjectThe title, description and link per language.
imagestringReplaces the main image in the same call.
Response fields data — 7
dataobjectThe slide as it now stands. Same shape as the detail endpoint.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/slides/2' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"status":"inactive","rank":1}'
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ status: 'inactive', rank: 1 }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['status' => 'inactive', 'rank' => 1]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// A rank does NOT push the others aside; give two slides the same number and the order blurs.
foreach ($order as $i => $slideId)
    Api::Website()->UpdateSlide(['id' => $slideId, 'rank' => $i]);

Deleting a Slide

delete/api/v1/admin/website/slides/{id}
Website/DeleteSlide admin

Removes a slide along with its image and video.

Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the slide removed.
Errors 3
slide_not_found404No such slide.
delete_failed500The slide could not be removed.
insufficient_scope403The key lacks the required scope.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/slides/2' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Rather than delete a seasonal slide, switch its STATUS off: image and texts survive.
Api::Website()->UpdateSlide(['id' => $id, 'status' => 'inactive']);

Replacing the Slide Image

put/api/v1/admin/website/slides/{id}/image
Website/SetSlideImage admin

Puts a new main image in place of the slide's current one.

Body 1
imagestringreqThe new main image. A thumbnail is built as well.
Response fields 201 — data — 1
urlstringThe new image's public address.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/website/slides/2/image' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"image":"https://ornek.com/yeni.jpg"}'
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/image`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ image: 'https://example.com/new.jpg' }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/image');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['image' => 'https://example.com/new.jpg']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// The update call does this too; the separate endpoint is for changing the image alone.
Api::Website()->SetSlideImage(['id' => $id, 'image' => $data]);

Setting a Slide Video

put/api/v1/admin/website/slides/{id}/video
Website/SetSlideVideo admin

Sets a background video on a slide.

Body 2
videostringreqThe video to upload. One format is accepted.
video_durationintHow long the video runs. The slider times its change by this.
Response fields 201 — data — 2
urlstringThe video's public address.
durationintThe length stored.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request 
curl -X PUT 'https://panel.example.com/api/v1/admin/website/slides/2/video' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"video":"https://ornek.com/klip.mp4","video_duration":12}'
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/video`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    video: 'https://example.com/clip.mp4',
    video_duration: 12,
  }),
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/video');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'video'          => 'https://example.com/clip.mp4',
        'video_duration' => 12,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// LEAVE THE LENGTH OUT and the slider change falls out of step; send the seconds with it.
Api::Website()->SetSlideVideo([
    'id' => $id, 'video' => $data, 'video_duration' => 12,
]);

Removing a Slide Video

delete/api/v1/admin/website/slides/{id}/video
Website/DeleteSlideVideo admin

Removes a slide's video, leaving it back on its image.

Response fields data — 2
deletedboolWhether the call ran. It comes back true even with no video there.
idintThe slide id.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request 
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/slides/2/video' \
  -H "Authorization: Bearer $API_KEY"
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/video`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/video');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// On a slide with no video the call passes QUIETLY; there is no need to check first.
Api::Website()->DeleteSlideVideo(['id' => $id]);

Pitfalls

A new slide reaches the homepage at once

Leave the status field out and the slide is created live, so visitors begin seeing it that moment. The homepage is the most visible place on the site, so create a slide you are still preparing switched off and turn it on once the texts are done.

The list carries no status and no rank

The listing gives the id, title, link and date, and carries no status and no rank field. From the list alone you cannot tell which slide is live or in what order they appear. Read each slide from the detail endpoint for that; there are rarely many.

A rank does not push the others aside

Giving one slide a rank does not shift the others. Give two slides the same number and which comes first is left open, so the order can change from one page load to the next. When reordering, write increasing numbers across all of them.

Without the length the change falls out of step

The slider times its move to the next slide by the length you give. Upload a video without it and the change falls out of step: the clip is cut off, or a frozen frame stays once it ends. Send the length together with the video.

The image cannot be removed, only replaced

The video has an endpoint that removes it and the image does not. The main image is what makes a slide a slide: you can replace it, yet you cannot leave it empty. Letting go of the image means deleting the slide, and that takes its image and video with it.

Cet article vous a-t-il été utile ?

Merci pour votre retour !

Besoin d'aide supplémentaire ?

Notre équipe d'assistance est disponible 24h/24 pour tout ce que vous ne trouvez pas ci-dessus.

Nous contacter Ouvrir un ticket

Nous utilisons des cookies pour vous garder connecté, mémoriser votre langue et votre devise, et améliorer le site. Politique relative aux cookies