Hogyan hitelesítem a kéréseket?

A Cathopic API-hoz intézett minden kérést hitelesíteni kell az API-kulcsoddal. Így kell helyesen hitelesíteni az API-hívásaidat.

Hitelesítési módszer

A Cathopic API API-kulcsos hitelesítést használ HTTP-fejléceken keresztül:

• Fejléc neve: x-api-key

• Fejléc értéke: A teljes API-kulcsod

• Szükséges ehhez: Az összes API-végpont

• Kis- és nagybetűre érzékeny: A fejlécneveknek és az értékeknek pontosan egyezniük kell

Alap hitelesítési példa

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);
?>

Hitelesítési hibák

Ha a hitelesítés sikertelen, hibaüzenetet kapsz:

Hiányzó API-kulcs:

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

Érvénytelen API-kulcs:

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

Inaktív API-kulcs:

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

Fontos emlékeztetők

Biztonság:

• Soha ne kódold be a kulcsokat: Használj környezeti változókat vagy biztonságos beállítást

• Csak szerveroldalon: Soha ne tegyél API-kulcsokat kliensoldali JavaScriptbe

• Csak HTTPS-t használj: A HTTP-n keresztül továbbított API-kulcsok sebezhetőek

• Rendszeres rotáció: Biztonság érdekében időnként cseréld a kulcsokat

Hibakezelés:

• Ellenőrizd az állapotkódokat: Mindig ellenőrizd a HTTP-válasz állapotát

• Hitelesítési hibák naplózása: Kövesd a sikertelen próbálkozásokat biztonsági megfigyeléshez

• Újrapróbálkozási logika bevezetése: Átmeneti hibák esetén exponenciális backoff-fal

• Előzetes ellenőrzés küldés előtt: Győződj meg róla, hogy az API-kulcs helyesen van betöltve

Hitelesítés tesztelése

Gyors teszt annak ellenőrzésére, hogy az API-kulcsod működik-e:

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}'

Várt válasz (siker):

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

Gyakori hibák

• Helytelen fejlécnév: A következő kell legyen: x-api-key, nem pedig api-key vagy Authorization

• Helytelen értékformátum: Használd a teljes kulcsot változtatás nélkül, ne tegyél elé "Bearer" előtagot

• Záró szóköz: Használat előtt vágd le az API-kulcs értékéből a felesleges szóközöket

• A kulcs nincs betöltve: Ellenőrizd, hogy a környezeti változó helyesen van-e beállítva

Hitelesítési problémák elhárításához lásd ebben a szakaszban a "Gyakori hitelesítési hibák" című részt.