Jak uwierzytelnić żądania?

Wszystkie żądania do API Cathopic muszą być uwierzytelniane przy użyciu klucza API. Oto jak prawidłowo uwierzytelnić wywołania API.

Metoda uwierzytelniania

API Cathopic wykorzystuje uwierzytelnianie kluczem API za pomocą nagłówków HTTP:

• Nazwa nagłówka: x-api-key

• Wartość nagłówka: Twój pełny klucz API

• Wymagane dla: Wszystkich endpointów API

• Rozróżnianie wielkości liter: Nazwy i wartości nagłówków muszą być zgodne dokładnie

Przykład podstawowego uwierzytelniania

cURL:

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Virgin Mary",
    "page": 1,
    "page_size": 20,
    "order": "popular"
  }'

JavaScript (fetch):

const response = await fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CATHOPIC_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  })
});
const data = await response.json();
console.log(data);

JavaScript (axios):

const axios = require('axios');
const response = await axios.post(
  'https://api.cathopic.com/resources',
  {
    query: 'Virgin Mary',
    page: 1,
    page_size: 20,
    order: 'popular'
  },
  {
    headers: {
      'x-api-key': process.env.CATHOPIC_API_KEY
    }
  }
);
console.log(response.data);

Python (requests):

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'query': 'Virgin Mary',
        'page': 1,
        'page_size': 20,
        'order': 'popular'
    }
)
data = response.json()
print(data)

PHP (cURL):

<?php $apiKey = getenv('CATHOPIC_API_KEY');
$ch = curl_init('https://api.cathopic.com/resources');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'query' => 'Virgin Mary',
    'page' => 1,
    'page_size' => 20,
    'order' => 'popular'
]));
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
?>

Błędy uwierzytelniania

Jeśli uwierzytelnianie się nie powiedzie, otrzymasz odpowiedź z błędem:

Brak klucza API:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Nieprawidłowy klucz API:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Nieaktywny klucz API:

HTTP 401 Unauthorized
{
  "error": "Unauthorized token"
}

Ważne przypomnienia

Bezpieczeństwo:

• Nigdy nie osadzaj na sztywno kluczy API: Używaj zmiennych środowiskowych lub bezpiecznej konfiguracji

• Tylko po stronie serwera: Nigdy nie umieszczaj kluczy API w kodzie JavaScript po stronie klienta

• Używaj wyłącznie HTTPS: Klucze API przesyłane przez HTTP są narażone

• Regularnie rotuj: Zmieniaj klucze okresowo dla bezpieczeństwa

Obsługa błędów:

• Sprawdzaj kody statusu: Zawsze weryfikuj status odpowiedzi HTTP

• Rejestruj niepowodzenia uwierzytelniania: Śledź nieudane próby w celu monitorowania bezpieczeństwa

• Wdroż logikę ponawiania: Z wykładniczym backoff dla błędów przejściowych

• Waliduj przed wysłaniem: Upewnij się, że klucz API został poprawnie załadowany

Testowanie uwierzytelniania

Szybki test, aby sprawdzić, czy Twój klucz API działa:

curl -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "page": 1, "page_size": 1}'

Oczekiwana odpowiedź (sukces):

{
  "total": 1234,
  "page": 1,
  "page_size": 1,
  "results": [ ... ]
}

Częste błędy

• Zła nazwa nagłówka: Musi być x-api-key, a nie api-key ani Authorization

• Nieprawidłowy format wartości: Użyj pełnego klucza dokładnie tak, jak jest, bez prefiksu „Bearer”

• Wiodące/końcowe białe znaki: Usuń zbędne spacje z wartości klucza API przed użyciem

• Klucz nie został załadowany: Sprawdź, czy zmienna środowiskowa jest ustawiona poprawnie

W celu rozwiązywania problemów z uwierzytelnianiem zobacz „Common authentication errors” w tej sekcji.