API калекцый

Атрыманне калекцыі

GET /3/collection/{collection_id} вяртае адну франшызу: назву, апісанне, постэр, фонавую выяву і масіў parts. Кожная частка ёсць кароткім апісаннем фільма з палямі, патрэбнымі для карткі, таму адзін выклік можа намаляваць цэлую паліцу франшызы.

У прыкладзе загружаецца калекцыя 10, фільмы Star Wars, і яе фільмы друкуюцца ў парадку выхаду.

curl -s "https://api.amodb.dev/3/collection/10?language=en-US" \
  -H "Authorization: Bearer $AMODB_KEY"

const url = 'https://api.amodb.dev/3/collection/10?language=en-US';
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } });
if (!res.ok) throw new Error(`amodb returned ${res.status}`);
const collection = await res.json();
console.log(collection.name);
for (const p of collection.parts) console.log(p.release_date || 'not dated', p.title);

import os
import requests

r = requests.get(
    "https://api.amodb.dev/3/collection/10",
    params={"language": "en-US"},
    headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"},
    timeout=10,
)
r.raise_for_status()
collection = r.json()
print(collection["name"])
for p in collection["parts"]:
    print(p.get("release_date") or "not dated", p["title"])

<?php
$url = 'https://api.amodb.dev/3/collection/10?language=en-US';
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
    throw new RuntimeException("amodb returned $status");
}
$collection = json_decode($body, true);
echo $collection['name'], PHP_EOL;
foreach ($collection['parts'] as $p) {
    echo $p['release_date'] ?: 'not dated', ' ', $p['title'], PHP_EOL;
}

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

type Collection struct {
	Name  string `json:"name"`
	Parts []struct {
		Title       string `json:"title"`
		ReleaseDate string `json:"release_date"`
	} `json:"parts"`
}

func main() {
	url := "https://api.amodb.dev/3/collection/10?language=en-US"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY"))
	client := &http.Client{Timeout: 10 * time.Second}
	res, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	if res.StatusCode != http.StatusOK {
		panic(res.Status)
	}
	var c Collection
	if err := json.NewDecoder(res.Body).Decode(&c); err != nil {
		panic(err)
	}
	fmt.Println(c.Name)
	for _, p := range c.Parts {
		date := p.ReleaseDate
		if date == "" {
			date = "not dated"
		}
		fmt.Println(date, p.Title)
	}
}

Параметры

• collection_idшляхабавязковы
  Лікавы id калекцыі, напрыклад 10.
• api_keyзапытадзін з двух
  Ваш ключ. Выкарыстоўвайце яго або загаловак Authorization: Bearer.
• languageзапыт
  Адна з 14 падтрымліваных моў, напрыклад en-US або fr-FR. Задае мову назвы і апісання кожнай часткі. Па змаўчанні en-US.

Уласныя name і overview калекцыі прыходзяць у тым выглядзе, як захаваны, і не змяняюцца ад language. Для некаторых калекцый яны не па-англійску.

Палі адказу

Прыклад адказу

Паказаны дзве з дзевяці частак.

{
  "id": 10,
  "name": "Star Wars Collection",
  "overview": "An epic space-opera theatrical film series, which depicts the adventures of various cha...",
  "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
  "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg",
  "parts": [
    {
      "adult": false,
      "backdrop_path": "/zqkmTXzjkAgXmEWLRsY4UpTWCeo.jpg",
      "genre_ids": [12, 28, 878],
      "id": 11,
      "original_language": "en",
      "original_title": "Star Wars",
      "overview": "Princess Leia is captured and held hostage by the evil Imperial forces in their effort...",
      "popularity": 70.481,
      "poster_path": "/fai0rspsNeJCS69wHNjOdWxcI7P.jpg",
      "release_date": "1977-05-25",
      "title": "Star Wars",
      "video": false,
      "vote_average": 8.207,
      "vote_count": 23025,
      "media_type": "movie"
    },
    {
      "adult": false,
      "backdrop_path": "/k9pshruhCpJAdH9RaGJO6jaWQ4X.jpg",
      "genre_ids": [12, 28, 878],
      "id": 1891,
      "original_language": "en",
      "original_title": "The Empire Strikes Back",
      "overview": "The epic saga continues as Luke Skywalker, in hopes of defeating the evil Galactic Empi...",
      "popularity": 29.9034,
      "poster_path": "/nNAeTmF4CtdSgMDplXTDPOpYzsX.jpg",
      "release_date": "1980-05-20",
      "title": "The Empire Strikes Back",
      "video": false,
      "vote_average": 8.393,
      "vote_count": 18990,
      "media_type": "movie"
    }
  ]
}

Доўгія радкі абрэзаны праз ... для гэтай старонкі. Сапраўдны адказ змяшчае поўны тэкст.

Як знайсці калекцыю фільма

Рэдка пачынаюць з id калекцыі. Пачынаюць з фільма, а запіс дэталяў фільма падказвае, да чаго ён належыць. Поле belongs_to_collection ёсць аб’ектам з id, name, poster_path і backdrop_path. Яно роўнае null для фільма, які не ўваходзіць у франшызу, напрыклад для фільма 550.

{
  "id": 11,
  "title": "Star Wars",
  "belongs_to_collection": {
    "id": 10,
    "name": "Star Wars Collection",
    "poster_path": "/pWVLFh4OuejTpUaDQbB1C4zoS2p.jpg",
    "backdrop_path": "/iY2ujEY2m68OTTlPFTiHub9joHS.jpg"
  }
}

Прыклад ніжэй ідзе па гэтай спасылцы ад фільма да яго франшызы за два запыты.

const base = 'https://api.amodb.dev/3';
const headers = { Authorization: `Bearer ${process.env.AMODB_KEY}` };

async function getJson(path) {
  const res = await fetch(`${base}${path}`, { headers });
  if (!res.ok) throw new Error(`${path} returned ${res.status}`);
  return res.json();
}

const movie = await getJson('/movie/11');
if (movie.belongs_to_collection) {
  const collection = await getJson(`/collection/${movie.belongs_to_collection.id}`);
  console.log(movie.title, 'is one of', collection.parts.length, 'films in', collection.name);
}

Афармленне і пошук

Постэр і фонавая выява франшызы ёсць палямі poster_path і backdrop_path запісу калекцыі. Складзіце з іх адрас файла, як апісана на старонцы выявы. amodb не прапануе шляхі /collection/{collection_id}/images і /collection/{collection_id}/translations, таму ў калекцыі няма спісу альтэрнатыўных постэраў і радкоў па мовах. Назвы частак замест гэтага залежаць ад параметра language, а пераклады апісваюць шляхі, што вяртаюць радкі па мовах.

Каб знайсці калекцыю па назве, скарыстайцеся GET /3/search/collection?query=matrix, апісаным на старонцы пошук. Кожны вынік мае id, name, overview, poster_path, backdrop_path, original_language, original_name і adult.

Памылкі

Поўны спіс гл. на старонцы памылкі, а ліміты планаў на старонцы ліміты запытаў.

Практычныя заўвагі

• Калекцыі групуюць толькі фільмы. Фільм мае не болей за адзін аб’ект belongs_to_collection, таму адзін фільм адпавядае адной франшызе.
• Часткі прыходзяць у парадку выхаду. Фільмы з пустой датай ідуць апошнімі, таму пазначайце іх як пакуль без даты.
• Запіс калекцыі кэшуецца на edge на 6 гадзін, як і іншыя дэталі, таму старонка франшызы можа выкарыстоўваць адзін адказ столькі часу.
• Частка нясе толькі кароткія палі. Працягласць, удзельнікаў і рэйтынгі па кожным фільме атрымлівайце праз дэталі фільма, калі карыстальнік яго адкрывае.
• Выкарыстоўвайце parts[].id як ключ фільма, а не яго месца ў франшызе. Парадак і даты з часам выпраўляюцца.
• Праверце, што name на вашай мове адлюстравання, перш чым паказваць яго. Некаторыя калекцыі маюць назву на іншай мове, і language яе не змяняе.