Ottieni una chiave API

Tutorial API film in Java

Crea una guida agli episodi in Java da riga di comando che stampa ogni episodio di una stagione con numero, data di messa in onda e durata. Usa l'HttpClient del JDK e Jackson, mappa il JSON in record, ritenta un 429 dopo il ritardo di Retry-After e mette in cache le risposte. Servono Java 17 o successivo e Maven 3.9.

.java Java Aggiornato il Vedi in Markdown

Costruirai EpisodeGuide, un programma da riga di comando. Eseguilo con l'ID di una serie TV e il numero di una stagione e stampa ogni episodio con numero, data di messa in onda, durata e nome. Usa l'HttpClient del JDK, Jackson 2.x, Java 17 o successivo e Maven 3.9. Calcola 20 minuti.

Passaggio 1: ottieni una chiave API

Una chiave richiede un piano prepagato, quindi inizia dalla pagina dei prezzi. Tutti i piani servono gli stessi dati, cambia solo la frequenza al minuto. Crea la chiave nella dashboard del tuo account ed esportala:

Il programma legge System.getenv("AMODB_KEY") e si rifiuta di partire senza.

Shell 
export AMODB_KEY="YOUR_API_KEY"

Passaggio 2: crea il progetto

Jackson è l'unica dipendenza. Crea la cartella, un pom.xml minimo e la directory dei sorgenti:

Funziona anche una versione 2.x più recente di jackson-databind.

Shell 
mkdir episode-guide && cd episode-guide
mkdir -p src/main/java
cat > pom.xml <<'EOF'
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>episode-guide</artifactId>
  <version>1.0</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>2.18.2</version>
    </dependency>
  </dependencies>
</project>
EOF

Passaggio 3: invia la prima richiesta

L'endpoint della stagione è GET /3/tv/{tv_id}/season/{season_number}, e Breaking Bad è la serie 1396. Questa classe stampa il codice di stato. Salvala come src/main/java/First.java per provarla da sola. Il comando di esecuzione del passaggio 7 funziona anche per lei se imposti -Dexec.mainClass=First.

Java 
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class First {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.amodb.dev/3/tv/1396/season/1"))
                .timeout(Duration.ofSeconds(10))
                .header("Authorization", "Bearer " + System.getenv("AMODB_KEY"))
                .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
                .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
    }
}

Passaggio 4: mappa il JSON in record

Una risposta di stagione ha un name e un array episodes. Ogni episodio ha episode_number, name, air_date e runtime, e gli ultimi due possono essere null per un episodio non ancora andato in onda. Usa Integer per un numero che può mancare. L'elenco completo dei campi è nella pagina stagioni ed episodi.

Java 
@JsonIgnoreProperties(ignoreUnknown = true)
public record Episode(
        @JsonProperty("episode_number") int number,
        String name,
        @JsonProperty("air_date") String airDate,
        Integer runtime) {}

Passaggio 5: gestisci errori e limiti di richieste

Leggi lo stato prima di toccare il corpo.

StatoCosa fa il programma
200Restituisce il corpo per Jackson.
401Solleva IOException nominando AMODB_KEY. Una chiave sbagliata fa fallire ogni chiamata, quindi nessun nuovo tentativo.
404Solleva un'eccezione con lo status_message, per esempio quando la stagione non esiste.
429Legge Retry-After, dorme da 1 a 30 secondi e reinvia la richiesta, al massimo 3 tentativi.
Timeout o errore di connessioneRilanciato come network error con la causa allegata.

Il corpo dell'errore ha la forma TMDB, quindi status_message è il testo da mostrare. La pagina errori elenca tutti i codici, e limiti di richieste spiega la finestra di 60 secondi.

Passaggio 6: metti le risposte in cache nei file

L'edge tiene i dettagli per 6 ore, quindi un elenco di episodi cambia di rado tra un'esecuzione e l'altra. Il programma scrive ogni corpo in un file nella directory temporanea, con un nome ricavato dal percorso della richiesta, e lo rilegge finché il file è più giovane del TTL. Un cache hit non invia nulla e non usa nessuna delle tue richieste al minuto.

Passaggio 7: il programma completo

Salvalo come src/main/java/EpisodeGuide.java.

Java 
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Objects;

public class EpisodeGuide {
    private static final String BASE = "https://api.amodb.dev/3";
    private static final String KEY = System.getenv("AMODB_KEY");
    private static final ObjectMapper MAPPER = new ObjectMapper();
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .build();
    private static final Path CACHE_DIR = Path.of(System.getProperty("java.io.tmpdir"), "amodb-cache");

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Episode(
            @JsonProperty("episode_number") int number,
            String name,
            @JsonProperty("air_date") String airDate,
            Integer runtime) {}

    @JsonIgnoreProperties(ignoreUnknown = true)
    public record Season(String name, List<Episode> episodes) {}

    static String get(String path) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(URI.create(BASE + path))
                .timeout(Duration.ofSeconds(10))
                .header("Authorization", "Bearer " + KEY)
                .header("Accept", "application/json")
                .GET()
                .build();
        for (int attempt = 1; ; attempt++) {
            HttpResponse<String> response;
            try {
                response = CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
            } catch (IOException e) {
                throw new IOException("network error: " + e, e);
            }
            int status = response.statusCode();
            if (status == 200) {
                return response.body();
            }
            if (status == 401) {
                throw new IOException("401: the key is invalid or suspended, check AMODB_KEY");
            }
            if (status == 429 && attempt < 3) {
                long seconds = response.headers().firstValueAsLong("Retry-After").orElse(1);
                Thread.sleep(Math.min(Math.max(seconds, 1), 30) * 1000);
                continue;
            }
            throw new IOException("amodb returned " + status + ": " + message(response.body()));
        }
    }

    static String message(String body) {
        try {
            return MAPPER.readTree(body).path("status_message").asText("no message");
        } catch (IOException e) {
            return "no message";
        }
    }

    static String cachedGet(String path, Duration ttl) throws IOException, InterruptedException {
        Files.createDirectories(CACHE_DIR);
        Path file = CACHE_DIR.resolve(path.replaceAll("[^A-Za-z0-9]", "_") + ".json");
        if (Files.exists(file)) {
            Instant modified = Files.getLastModifiedTime(file).toInstant();
            if (modified.plus(ttl).isAfter(Instant.now())) {
                return Files.readString(file);
            }
        }
        String body = get(path);
        Files.writeString(file, body);
        return body;
    }

    public static void main(String[] args) {
        if (args.length != 2) {
            System.err.println("Usage: EpisodeGuide <tv_id> <season_number>");
            System.exit(2);
        }
        if (KEY == null || KEY.isBlank()) {
            System.err.println("Set AMODB_KEY first.");
            System.exit(2);
        }
        String path;
        try {
            path = "/tv/" + Integer.parseInt(args[0]) + "/season/" + Integer.parseInt(args[1]) + "?language=en-US";
        } catch (NumberFormatException e) {
            System.err.println("The series id and season number must be integers.");
            System.exit(2);
            return;
        }
        try {
            Season season = MAPPER.readValue(cachedGet(path, Duration.ofHours(6)), Season.class);
            System.out.println(season.name() + ", " + season.episodes().size() + " episodes");
            for (Episode ep : season.episodes()) {
                System.out.printf("%2d  %-10s  %-7s  %s%n",
                        ep.number(),
                        Objects.requireNonNullElse(ep.airDate(), "TBA"),
                        ep.runtime() == null ? "?" : ep.runtime() + " min",
                        ep.name());
            }
        } catch (IOException e) {
            System.err.println("error: " + e.getMessage());
            System.exit(1);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            System.exit(1);
        }
    }
}

Compila ed eseguilo per la stagione 1 della serie 1396:

L'output ha una riga di intestazione con il nome della stagione e il numero di episodi, poi una riga per episodio. Un episodio senza data di messa in onda mostra TBA, e uno senza durata mostra ?. Esegui il comando due volte: la seconda legge il file dalla directory temporanea e non invia alcuna richiesta, finché non passano 6 ore. Elimina la cartella amodb-cache per forzare dati freschi.

Tieni l'HttpClient e l'ObjectMapper in campi statici. Entrambi sono thread safe e costosi da costruire, quindi un'istanza per processo è il modello normale, anche in un servizio web.

Shell 
mvn -q compile exec:java -Dexec.mainClass=EpisodeGuide -Dexec.args="1396 1"

Prossimi passi

  • Fai un ciclo dalla stagione 1 a number_of_seasons dai dettagli della serie TV e stampa l'intera serie.
  • Mostra il prossimo episodio di una serie in corso con next_episode_to_air.
  • Aggiungi un terzo argomento per il parametro language, e vedi quali tag sono serviti nella pagina lingue.
  • Confronta con lo stesso schema in Go, oppure parti dalla panoramica dell'API guida agli episodi.