Jak działa Content API Nelavio: integracja z React, Next.js i SvelteKit

Content API w Nelavio służy do programowego pobierania wygenerowanych treści i danych SEO bezpośrednio do własnych aplikacji frontendowych lub systemów CMS. Zamiast ręcznego eksportu, dane przesyłane są przez bezpieczne połączenie, co pozwala na zachowanie aktualności informacji na stronie bez ingerencji w kod aplikacji przy każdej zmianie.

Poniższy przewodnik opisuje architekturę endpointów, proces uwierzytelniania oraz konkretne kroki integracji dla trzech popularnych środowisk: React, Next.js i SvelteKit.

Architektura i endpointy Content API

Content API udostępnia dane poprzez zdefiniowane endpointy REST. Każdy endpoint odpowiada określonemu typowi danych dostępnych w systemie Nelavio. Komunikacja z API opiera się na standardowych żądaniach HTTP, a odpowiedzi zwracane są w formacie JSON.

Struktura żądania do API składa się z:

• Adresu URL endpointu,
• Metody HTTP (zazwyczaj GET dla pobierania danych),
• Nagłówków uwierzytelniających,
• Opcjonalnych parametrów zapytania (np. filtrowanie czy paginacja, w zależności od specyfiki endpointu).

Odpowiedź JSON zawiera obiekt z danymi. Przed przypisaniem danych do stanu aplikacji, należy zweryfikować strukturę zwracanego obiektu z dokumentacją konkretnego endpointu.

Uwierzytelnianie API i tokeny

Dostęp do Content API jest chroniony i wymaga uwierzytelniania. Proces ten opiera się na tokenach API, co jest standardowym mechanizmem dla interfejsów REST. Tokeny generowane są w panelu konta Nelavio w sekcji dotyczącej bezpieczeństwa i integracji.

Przekazywanie tokenu w żądaniu

Token musi być dołączany do każdego żądania HTTP w nagłówku Authorization z użyciem schematu Bearer. Przykładowy nagłówek wygląda następująco:

GET /api/v1/content/endpoint
Host: api.nelavio.com
Authorization: Bearer NELAVIO_API_TOKEN

Gdzie NELAVIO_API_TOKEN to wygenerowany ciąg znaków. Jeśli token jest nieprawidłowy lub brakuje nagłówka, API zwróci błąd 401 Unauthorized.

Bezpieczeństwo tokenów

Tokeny API należy traktować jako poufne dane dostępowe. W aplikacjach frontendowych kluczowe jest, aby nie ujawniać tokenu w kodzie po stronie klienta (w przeglądarce). Wymaga to architektury, w której żądania do Content API przechodzą przez warstwę pośrednią (backend lub funkcje serverless) lub wykorzystują mechanizmy renderowania po stronie serwera (SSR).

Integracja z React

W klasycznych aplikacjach React (SPA - Single Page Application) wykonanie żądania bezpośrednio z przeglądarki wymagałoby ujawnienia tokenu API. Aby zachować bezpieczeństwo, należy zaimplementować backend proxy lub korzystać z funkcji serverless, które dodadzą nagłówek Authorization po stronie serwera.

Jeśli architektura posiada własny endpoint proxy pod adresem /api/nelavio-content, integracja po stronie klienta wygląda następująco:

import { useState, useEffect } from 'react';

function ContentComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetch('/api/nelavio-content')
      .then((response) => {
        if (!response.ok) {
          throw new Error('Błąd pobierania danych z API');
        }
        return response.json();
      })
      .then((jsonData) => {
        setData(jsonData);
        setLoading(false);
      })
      .catch((err) => {
        setError(err.message);
        setLoading(false);
      });
  }, []);

  if (loading) return <p>Ładowanie danych...</p>;
  if (error) return <p>Błąd: {error}</p>;

  return (
    <div>
      {/* Renderowanie danych z API */}
    </div>
  );
}

W tym podejściu React odpowiada za cykl życia komponentu i obsługę stanów (ładowanie, błąd, sukces), podczas gdy uwierzytelnianie jest oddelegowane do serwera proxy.

Integracja z Next.js

Next.js oferuje wbudowane mechanizmy renderowania po stronie serwera, co rozwiązuje problem ukrycia tokenu API. W zależności od użytego routera (App Router lub Pages Router), implementacja różni się miejscem wykonania żądania.

Podejście z App Router (Server Components)

W Next.js App Router domyślnym trybem są Server Components, co pozwala na bezpośrednie wywołanie Content API z poziomu serwera bez ujawniania tokenu w pakiecie JavaScript wysyłanym do przeglądarki.

// app/page.jsx
const NELAVIO_API_TOKEN = process.env.NELAVIO_API_TOKEN;

async function getData() {
  const res = await fetch('https://api.nelavio.com/v1/content/endpoint', {
    headers: {
      Authorization: `Bearer ${NELAVIO_API_TOKEN}`,
    },
    cache: 'no-store' // lub 'force-cache' w zależności od wymagań aktualności danych
  });

  if (!res.ok) {
    throw new Error('Nie udało się pobrać danych z Content API');
  }

  return res.json();
}

export default async function Page() {
  const data = await getData();

  return (
    <main>
      {/* Renderowanie na podstawie zmiennej data */}
    </main>
  );
}

Zmienna środowiskowa NELAVIO_API_TOKEN musi być dodana do pliku .env.local i nie może posiadać prefiksu NEXT_PUBLIC_, aby Next.js nie osadzał jej w kodzie klienta.

Integracja z SvelteKit

SvelteKit opiera się na architekturze, w której pobieranie danych odbywa się w tzw. funkcjach load uruchamianych na serwerze. Pozwala to na bezpieczne użycie zmiennych środowiskowych serwera.

W SvelteKit zmienne prywatne odczytywane są z obiektu $env/static/private.

// src/routes/+page.server.js
import { NELAVIO_API_TOKEN } from '$env/static/private';

export async function load({ fetch }) {
  const response = await fetch('https://api.nelavio.com/v1/content/endpoint', {
    headers: {
      Authorization: `Bearer ${NELAVIO_API_TOKEN}`,
    },
  });

  if (!response.ok) {
    return {
      status: response.status,
      error: new Error('Błąd połączenia z Content API Nelavio')
    };
  }

  const data = await response.json();

  return {
    props: {
      data
    }
  };
}

Dane zwrócone przez funkcję load są automatycznie dostępne w komponencie strony jako props. Cały proces uwierzytelniania i komunikacji z Content API odbywa się po stronie serwera, a do przeglądarki trafia jedynie gotowy HTML i czyste dane w formacie JSON (podczas tzw. hydracji).

API błędy i limity zapytań

Komunikacja z Content API wymaga uwzględnienia mechanizmów ograniczających. Nelavio stosuje limity zapytań (rate limits), aby zapewnić stabilność infrastruktury. Szczegółowe wartości limitów zależą od planu subskrypcyjnego.

Przy implementacji integracji należy:

1. Obsługiwać błędy HTTP: Błąd 401 Unauthorized oznacza problem z tokenem. Błąd 429 Too Many Requests sygnalizuje przekroczenie limitu zapytań w danym oknie czasowym.
2. Wdrożyć mechanizm ponownych prób (retry): Po otrzymaniu błędu 429 aplikacja powinna odczekać czas wskazany w nagłówkach odpowiedzi (np. Retry-After) i ponowić żądanie.
3. Zaimplementować cache: W środowiskach SSR (Next.js, SvelteKit) należy skonfigurować politykę cache dla odpowiedzi API, aby zmniejszyć liczbę żądań do Nelavio i przyspieszyć renderowanie stron.

Lista kontrolna wdrożenia Content API

Przed wdrożeniem integracji na środowisko produkcyjne, zweryfikuj poniższe kroki:

• Token API został wygenerowany w panelu Nelavio.
• Token jest przechowywany wyłącznie w zmiennych środowiskowych serwera (np. .env.local w Next.js, $env/static/private w SvelteKit).
• Nagłówek Authorization: Bearer <token> jest poprawnie dołączany do każdego żądania.
• Kod frontendowy nie zawiera odniesień do tokenu ani bezpośrednich żądań do chronionych endpointów z przeglądarki.
• Zaimplementowano obsługę błędów sieciowych i kodów HTTP (szczególnie 401 i 429).
• Skonfigurowano cache dla żądań serwerowych w celu optymalizacji użycia limitów API.
• Przetestowano strukturę odpowiedzi JSON i przypisano ją do modelu danych w aplikacji.

Prawidłowa integracja z Content API pozwala na automatyczne pobieranie treści i regularnych poprawek SEO wygenerowanych w systemie Nelavio, utrzymując jednocześnie wysoką wydajność i bezpieczeństwo aplikacji docelowej. Aby uzyskać dostęp do endpointów i wygenerować token, zaloguj się do swojego konta w panelu Nelavio.