Dokumentimi i API-t

API publike REST për qasje në pikët dhe renditjen e universiteteve.

URL bazë: /api/v1/ — Të gjitha përgjigjet kthejnë JSON. Nuk kërkohet autentikim.

OpenAPI Spec

API v2 tani i disponueshëm! Përgjigje të mbështjella, audit-logs, HMAC opsional, enveloped responses dhe endpoint-e të reja si /api/v2/scan-diff, /api/v2/leaderboard/{category}, /api/v2/regressions.

Schema V2

GET /api/v1/universities

Listo të gjitha universitetet e skanuara me paginim.

Parametrat: page (default: 1), limit (default: 20, max: 100), search (filter by name/domain), country (filter by country), sort (name|domain|country|created_at), order (asc|desc)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/universities?page=1&limit=20'

const res = await fetch('/api/v1/universities?page=1&limit=20');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities',
                   params={'page': 1, 'limit': 20})
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": [
        {
            "id": 1,
            "domain": "example.edu",
            "name": "Example University",
            "country": "US",
            "created_at": "2025-01-10 08:00:00"
        }
    ],
    "meta": {
        "page": 1,
        "limit": 20,
        "total": 45
    }
}

GET /api/v1/universities/{id}

Merr detajet për një universitet specifik.

Parametrat: id (obliguar)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/universities/1'

const res = await fetch('/api/v1/universities/1');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1')
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": {
        "id": 1,
        "domain": "example.edu",
        "name": "Example University",
        "country": "US",
        "created_at": "2025-01-10 08:00:00",
        "scan_count": 3
    }
}

GET /api/v1/universities/{id}/scores

Merr të gjitha pikët e llogaritura për skanimin e fundit.

Parametrat: id (obliguar)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/universities/1/scores'

const res = await fetch('/api/v1/universities/1/scores');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1/scores')
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": {
        "scan_id": 42,
        "overall_score": 72.5,
        "webo_composite_score": 68.2,
        "tech_composite_score": 75.1,
        "research_composite_score": 80.3,
        "presence_composite_score": 65.9,
        "tech_ssl_score": 95,
        "tech_speed_desktop_score": 82,
        "...": "30+ sub-scores"
    }
}

GET /api/v1/rankings

Merr të gjitha universitetet të renditura sipas pikëve.

Parametrat: page (default: 1), limit (default: 50), country (filter), min_score, max_score, sort (overall|webometrics|technical|research|presence)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/rankings'

const res = await fetch('/api/v1/rankings');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/rankings')
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": [
        {
            "rank": 1,
            "id": 5,
            "domain": "top-uni.edu",
            "name": "Top University",
            "country": "US",
            "overall_score": 89.2,
            "webometrics_score": 68.2,
            "technical_score": 75.1,
            "research_score": 80.3,
            "presence_score": 65.9
        }
    ]
}

GET /api/v1/stats

Merr statistikat e platformës.

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/stats'

const res = await fetch('/api/v1/stats');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/stats')
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": {
        "total_universities": 45,
        "total_scans": 312,
        "average_score": 54.8
    }
}

GET /api/v1/compare

Krahaso universitete duke përdorur ID-të e tyre.

Parametrat: ids (obliguar) — comma-separated IDs (2-10)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/compare?ids=1,2'

const res = await fetch('/api/v1/compare?ids=1,2');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/compare',
                   params={'ids': '1,2'})
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": [
        {
            "university": {
                "id": 1,
                "domain": "uni-a.edu",
                "name": "University A"
            },
            "scan_date": "2025-01-10",
            "scores": {
                "overall_score": 72.5
            }
        }
    ]
}

GET /api/v1/universities/{id}/export

Eksporto të gjitha të dhënat e universitetit si JSON (pikët, historia, rekomandimet).

Parametrat: id (obliguar)

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/api/v1/universities/1/export'

const res = await fetch('/api/v1/universities/1/export');
const data = await res.json();
console.log(data);

import requests

res = requests.get('http://localhost/api/v1/universities/1/export')
data = res.json()
print(data)

Struktura e Përgjigjes

{
    "success": true,
    "data": {
        "exported_at": "2025-01-10T08:00:00+00:00",
        "university": {
            "id": 1,
            "domain": "example.edu"
        },
        "latest_scores": {
            "overall_score": 72.5
        },
        "recommendations": [],
        "scan_history": []
    }
}

GET /health

Kontrollo statusin e sistemit (database, disk, cache).

Shembuj Kodi

curl -s 'academyscanner.cyber-aab.com/health'

const res = await fetch('/health');
const data = await res.json();
console.log(data.status);

import requests

res = requests.get('http://localhost/health')
data = res.json()
print(data['status'])

Struktura e Përgjigjes

{
    "status": "healthy",
    "version": "3.7.0",
    "timestamp": "2025-01-10T08:00:00+00:00",
    "checks": {
        "database": {
            "status": "ok"
        },
        "disk": {
            "status": "ok",
            "free_gb": 45.2
        },
        "logs": {
            "status": "ok",
            "writable": true
        },
        "cache": {
            "status": "ok",
            "entries": 150
        }
    }
}

Webhooks

Merrni njoftim automatik kur një skanim përfundon. Konfiguroni webhooks nga Admin → Webhooks.

Ngjarjet

Ngjarja	Përshkrimi
`scan.completed`	Skanimi përfundoi me sukses

Formati i Payload

{
  "event": "scan.completed",
  "timestamp": "2025-01-10T08:00:00+00:00",
  "data": {
    "scan_id": 42,
    "university_id": 5,
    "domain": "example.edu",
    "overall_score": 72.5,
    "completed_at": "2025-01-10T08:00:00+00:00"
  }
}

Verifikimi i Nënshkrimit

Çdo kërkesë webhook përfshin header X-Webhook-Signature: sha256=<hmac>

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, $your_secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

Kufizimi i Kërkesave

API publike ka kufi prej 100 kërkesave në orë për IP.

Header	Përshkrimi
`X-RateLimit-Remaining`	Numri i kërkesave të mbetura