mirror of
https://github.com/Shineii86/AniKotoAPI.git
synced 2026-10-22 10:55:10 +00:00
docs: Complete documentation overhaul with live API data + bug fixes
Documentation (5800+ lines total): - endpoints.md: All 43 endpoints documented with real response examples, param tables, response patterns, common workflows, error formats - streaming.md: Complete streaming workflow guide with HLS.js/Plyr/Video.js integration, M3U8 proxy explanation, error handling - examples.md: Working code examples in cURL, JS fetch, Python requests, Node.js axios, HTML/JS player integration (2240 lines) - architecture.md: Full project structure, request flow diagrams, caching strategy, mirror failover, security, deployment notes - index.md: Overview with quick start, feature highlights, endpoint tables Bug fixes: - episodeList.extractor: Parse JSON response before Cheerio (was passing raw JSON string as HTML, causing escaped quotes in IDs) - episodeListAjax.extractor: Same JSON parsing fix - topAnimeRankings.controller: Fix JSDoc and default sort from top to day (actual values are day/week/month, not top/newest) - apiRoutes.js: Fix OpenAPI spec sort description for top-rankings Tests: 35/35 passing
This commit is contained in:
Shinei Nouzen
+871
-231
File diff suppressed because it is too large
Load Diff
+280
-26
@@ -6,35 +6,42 @@ Base URL: `https://anikototvapi.vercel.app/api`
|
||||
|
||||
## Pagination
|
||||
|
||||
All list endpoints include pagination metadata in the response:
|
||||
Most list endpoints return a `totalPages` field for pagination:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": {
|
||||
"data": [...],
|
||||
"totalPages": 296,
|
||||
"data": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the `page` query parameter to navigate: `?page=2`
|
||||
|
||||
**Only `/api/filter` returns the full pagination object:**
|
||||
|
||||
```json
|
||||
{
|
||||
"results": {
|
||||
"totalPages": 1,
|
||||
"data": [],
|
||||
"pagination": {
|
||||
"currentPage": 1,
|
||||
"totalPages": 294,
|
||||
"totalItems": 8820,
|
||||
"totalPages": 1,
|
||||
"totalItems": 0,
|
||||
"itemsPerPage": 30,
|
||||
"hasNext": true,
|
||||
"hasNext": false,
|
||||
"hasPrev": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|:---|:---|:---|
|
||||
| `currentPage` | `number` | Current page number (1-indexed) |
|
||||
| `totalPages` | `number` | Total number of pages available |
|
||||
| `totalItems` | `number` | Estimated total items across all pages |
|
||||
| `itemsPerPage` | `number` | Number of items per page (default: 30) |
|
||||
| `hasNext` | `boolean` | Whether there is a next page |
|
||||
| `hasPrev` | `boolean` | Whether there is a previous page |
|
||||
**Endpoints with `totalPages` pagination:** `/api/search`, `/api/most-popular`, `/api/new-release`, `/api/newly-added`, `/api/latest-updated`, `/api/az-list/:letter`, `/api/filter`, `/api/genre/:name`, `/api/type/:name`, `/api/status/:name`
|
||||
|
||||
**Endpoints with pagination:** `/api/search`, `/api/most-popular`, `/api/new-release`, `/api/newly-added`, `/api/latest-updated`, `/api/az-list/:letter`, `/api/filter`, `/api/genre/:name`, `/api/type/:name`, `/api/status/:name`
|
||||
**Endpoints with flat arrays (no pagination):** `/api/spotlight`, `/api/trending`, `/api/top-ten`, `/api/suggestions`, `/api/recently-updated`, `/api/completed`, `/api/upcoming`, `/api/top-rankings`, `/api/mirrors`, `/api/schedule`
|
||||
|
||||
---
|
||||
|
||||
@@ -136,12 +143,14 @@ Get detailed info about an anime.
|
||||
|
||||
| Param | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `id` | string | Yes | Anime slug (e.g., `road-of-naruto-ggjw8`) |
|
||||
| `id` | string | Yes | Anime slug with random hash (e.g., `naruto-shippuuden-movie-6-road-to-ninja-w2wqq`) |
|
||||
|
||||
> **Important:** Slugs now include random hashes (e.g., `one-piece-odmau`). Get valid slugs from `/search` or `/most-popular` results.
|
||||
|
||||
**Request:**
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/info?id=road-of-naruto-ggjw8"
|
||||
curl "https://anikototvapi.vercel.app/api/info?id=naruto-shippuuden-movie-6-road-to-ninja-w2wqq"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
@@ -150,13 +159,26 @@ curl "https://anikototvapi.vercel.app/api/info?id=road-of-naruto-ggjw8"
|
||||
{
|
||||
"success": true,
|
||||
"results": {
|
||||
"title": "Road of Naruto",
|
||||
"type": "ONA",
|
||||
"slug": "naruto-shippuuden-movie-6-road-to-ninja-w2wqq",
|
||||
"animeId": 786,
|
||||
"title": "Naruto: Shippuuden Movie 6: Road to Ninja",
|
||||
"japaneseTitle": "Naruto: Shippuuden Movie 6 - Road to Ninja",
|
||||
"altNames": "Naruto: Shippuuden Movie 6 - Road to Ninja;Naruto Movie 9",
|
||||
"poster": "https://cdn.anipixcdn.co/thumbnail/43dd49b4fdb9bede653e94468ff8df1e.jpg",
|
||||
"backgroundImage": "'",
|
||||
"synopsis": "Returning home to Konohagakure, the young ninja celebrate defeating a group of supposed Akatsuki...",
|
||||
"type": "Movie",
|
||||
"premiered": "Summer 2012",
|
||||
"aired": "Jul 28, 2012",
|
||||
"status": "Finished Airing",
|
||||
"totalEpisodes": null,
|
||||
"synopsis": "In celebration of 20 years of Naruto, Studio Pierrot posted an anniversary PV on their YouTube channel...",
|
||||
"malId": "53236",
|
||||
"genres": ["Action", "Fantasy", "Shounen"]
|
||||
"malScore": "7.84",
|
||||
"duration": "1 hr 39 min",
|
||||
"episodes": "1",
|
||||
"studios": ["Pierrot"],
|
||||
"producers": ["TV Tokyo", "Shueisha"],
|
||||
"genres": ["Action", "Comedy", "Supernatural"],
|
||||
"rating": "PG-13",
|
||||
"reviewCount": "0"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -687,17 +709,36 @@ Returns paginated list of upcoming anime with sub/dub counts, type, and rating.
|
||||
|
||||
## GET /top-rankings
|
||||
|
||||
Get top-ranked anime (source site's top section).
|
||||
Get top-ranked anime with sort options.
|
||||
|
||||
| Param | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `sort` | string | No | Sort mode: `day` (default), `week`, or `month` |
|
||||
| `page` | number | No | Page number (default: 1) |
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/top-rankings"
|
||||
curl "https://anikototvapi.vercel.app/api/top-rankings?sort=week"
|
||||
```
|
||||
|
||||
Returns paginated list with rank numbers extracted from CSS classes.
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": [
|
||||
{
|
||||
"rank": 1,
|
||||
"slug": "demon-slayer-kimetsu-no-yaiba-infinity-castle-4tmun",
|
||||
"poster": "https://cdn.anipixcdn.co/thumbnail/...",
|
||||
"title": "Demon Slayer: Kimetsu no Yaiba Infinity Castle",
|
||||
"japaneseTitle": "Kimetsu no Yaiba Movie: Mugen Jou-hen",
|
||||
"sub": 1,
|
||||
"dub": 1,
|
||||
"type": "Movie"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -730,7 +771,9 @@ Get completed anime sorted by score.
|
||||
curl "https://anikototvapi.vercel.app/api/completed"
|
||||
```
|
||||
|
||||
Returns paginated list of finished anime from `section.top-table[data-name='completed']`.
|
||||
Returns flat array of finished anime.
|
||||
|
||||
> **Note:** The `type` field in completed results contains the **air date** (e.g., `"2016-05-14"`), not the anime type (TV/Movie/etc).
|
||||
|
||||
---
|
||||
|
||||
@@ -796,3 +839,214 @@ curl "https://anikototvapi.vercel.app/api/stream/ts-proxy?url=https://example.co
|
||||
```
|
||||
|
||||
Returns binary video segment with `Content-Type: video/mp2t` and `Access-Control-Allow-Origin: *`.
|
||||
|
||||
---
|
||||
|
||||
## System Endpoints
|
||||
|
||||
### GET /health
|
||||
|
||||
Health check endpoint. No parameters required.
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/health"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": {
|
||||
"status": "healthy",
|
||||
"version": "2.2.0",
|
||||
"uptime": "0h 1m 21s",
|
||||
"uptimeSeconds": 81,
|
||||
"timestamp": "2026-07-30T02:20:46.153Z",
|
||||
"node": "v26.4.0",
|
||||
"memory": {
|
||||
"used": "99MB",
|
||||
"total": "150MB"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /stats
|
||||
|
||||
API statistics endpoint. No parameters required.
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/stats"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": {
|
||||
"uptime": "81s",
|
||||
"requests": {
|
||||
"total": 37,
|
||||
"errors": 9,
|
||||
"successRate": "75.7%"
|
||||
},
|
||||
"cache": {
|
||||
"type": "in-memory",
|
||||
"ttl": "5 minutes",
|
||||
"description": "Map-based cache with TTL expiration"
|
||||
},
|
||||
"endpoints": 38,
|
||||
"timestamp": "2026-07-30T02:20:46.205Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /cache/stats
|
||||
|
||||
Cache statistics endpoint. No parameters required.
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/cache/stats"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": {
|
||||
"hits": 0,
|
||||
"misses": 28,
|
||||
"sets": 26,
|
||||
"deletes": 0,
|
||||
"size": 26,
|
||||
"hitRate": "0.00%"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /mirrors
|
||||
|
||||
Mirror status endpoint. No parameters required.
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/mirrors"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"results": [
|
||||
{
|
||||
"name": "Primary",
|
||||
"url": "https://anikototv.to",
|
||||
"priority": 1,
|
||||
"status": "online",
|
||||
"latency": "6115ms",
|
||||
"isCurrent": true
|
||||
},
|
||||
{
|
||||
"name": "Regional CZ",
|
||||
"url": "https://anikoto.cz",
|
||||
"priority": 2,
|
||||
"status": "online",
|
||||
"latency": "672ms",
|
||||
"isCurrent": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### POST /mirrors/reset
|
||||
|
||||
Reset mirror cache. No parameters required.
|
||||
|
||||
```bash
|
||||
curl -X POST "https://anikototvapi.vercel.app/api/mirrors/reset"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Mirror cache reset"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### GET /openapi
|
||||
|
||||
OpenAPI 3.0.3 specification. No parameters required.
|
||||
|
||||
```bash
|
||||
curl "https://anikototvapi.vercel.app/api/openapi"
|
||||
```
|
||||
|
||||
Returns the full OpenAPI spec document with all endpoint definitions, tags, and server information.
|
||||
|
||||
---
|
||||
|
||||
## Response Patterns
|
||||
|
||||
| Pattern | Format | Endpoints |
|
||||
|:---|:---|:---|
|
||||
| **Flat array** | `results: [...]` | `/spotlight`, `/trending`, `/top-ten`, `/suggestions`, `/recently-updated`, `/completed`, `/upcoming`, `/top-rankings`, `/mirrors`, `/schedule` |
|
||||
| **Paginated data** | `results: { totalPages, data: [...] }` | `/search`, `/most-popular`, `/new-release`, `/newly-added`, `/latest-updated`, `/genre/:name`, `/type/:name`, `/status/:name`, `/az-list/:letter` |
|
||||
| **Full pagination** | `results: { totalPages, data: [...], pagination: {...} }` | `/filter` only |
|
||||
| **Three-period** | `results: { today/week/month: [...] }` or `{ day/week/month: [...] }` | `/top-ten`, `/trending-sidebar` |
|
||||
| **Single object** | `results: {...}` | `/home`, `/info`, `/episodes`, `/episodes-ajax`, `/random`, `/health`, `/stats`, `/cache/stats`, `/stream-qualities` |
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Streaming Workflow
|
||||
|
||||
```
|
||||
1. GET /episodes/{animeId} → Get episode list with server_ids
|
||||
2. GET /servers?ids={ids} → Get available servers with link_ids
|
||||
3. GET /stream?id={link_id} → Get embed URL + skip data
|
||||
4. GET /stream/resolve?id={link_id} → Get actual m3u8/mp4 URL
|
||||
5. GET /stream/qualities?url={m3u8} → Get available qualities
|
||||
6. GET /stream/proxy?url={m3u8} → Get CORS-free proxied playlist
|
||||
```
|
||||
|
||||
### Discovery Workflow
|
||||
|
||||
```
|
||||
1. GET / → Homepage: spotlights, trending, genres
|
||||
2. GET /search?q= → Search by keyword
|
||||
3. GET /info?id= → Get anime details
|
||||
4. GET /episodes/ → Get episode list
|
||||
5. GET /seasons/ → Get all seasons
|
||||
6. GET /watch-order/ → Get watch order for franchises
|
||||
```
|
||||
|
||||
### Filter & Browse Workflow
|
||||
|
||||
```
|
||||
1. GET /genre/{name} → Browse by genre
|
||||
2. GET /type/{name} → Browse by type (TV, Movie, OVA)
|
||||
3. GET /status/{name} → Browse by status (airing, completed)
|
||||
4. GET /filter?... → Advanced multi-parameter filter
|
||||
5. GET /az-list/{letter} → Browse alphabetically
|
||||
6. GET /top-rankings?sort=day → Top ranked anime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
// ══════ END: endpoints.md ══════
|
||||
|
||||
+2039
-265
File diff suppressed because it is too large
Load Diff
+405
@@ -0,0 +1,405 @@
|
||||
# // === HEADER ===
|
||||
# AniKotoAPI v2.2.0
|
||||
# Free REST API for Anime Data
|
||||
# Scraping anikototv.to with Cheerio
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
> A fast, free REST API that scrapes anime data from **anikototv.to**.
|
||||
> Built with Node.js, Cheerio, and deployed on Vercel serverless functions.
|
||||
|
||||
---
|
||||
|
||||
## // === QUICK START ===
|
||||
|
||||
### Get started in 3 steps:
|
||||
|
||||
**Step 1** — Make your first request:
|
||||
|
||||
```bash
|
||||
curl https://anikototvapi.vercel.app/api/
|
||||
```
|
||||
|
||||
**Step 2** — Search for an anime:
|
||||
|
||||
```bash
|
||||
curl https://anikototvapi.vercel.app/api/search?q=naruto
|
||||
```
|
||||
|
||||
**Step 3** — Get anime info:
|
||||
|
||||
```bash
|
||||
curl https://anikototvapi.vercel.app/api/info?link=/anime/naruto
|
||||
```
|
||||
|
||||
That's it. No API keys required.
|
||||
|
||||
---
|
||||
|
||||
## // === FEATURES ===
|
||||
|
||||
| Feature | Description |
|
||||
|---|---|
|
||||
| **38+ Endpoints** | Full coverage of anime data, streaming, and discovery |
|
||||
| **28 HTML Scrapers** | Cheerio-based scrapers for robust data extraction |
|
||||
| **28 Route Handlers** | Organized controllers with clean separation of concerns |
|
||||
| **5 Mirror Domains** | Automatic failover across multiple source domains |
|
||||
| **LRU Cache** | Per-endpoint TTL caching for performance |
|
||||
| **Rate Limiting** | 100 requests per 15 minutes per IP |
|
||||
| **GZIP Compression** | Compressed responses for faster transfers |
|
||||
| **Vercel Deployment** | Zero-config serverless deployment |
|
||||
| **OpenAPI Spec** | Auto-generated API documentation at `/api/openapi` |
|
||||
| **Health Checks** | System status and cache monitoring endpoints |
|
||||
|
||||
---
|
||||
|
||||
## // === ENDPOINTS OVERVIEW ===
|
||||
|
||||
### Home
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/` | Homepage data: featured, spotlight, sidebar content |
|
||||
|
||||
### Anime
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/info` | Full anime info, episodes, relations, recommendations |
|
||||
| GET | `/api/seasons/:id` | Season/episode details for an anime |
|
||||
| GET | `/api/watch-order/:id` | Canonical watch order for a series |
|
||||
|
||||
### Search
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/search` | Search anime by title |
|
||||
| GET | `/api/search/suggest` | Autocomplete suggestions |
|
||||
| GET | `/api/suggestions` | Trending/general suggestions |
|
||||
|
||||
### Episodes
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/episodes/:id` | Episode list for an anime |
|
||||
| GET | `/api/episodes-ajax/:id` | Lazy-loaded episode pagination |
|
||||
|
||||
### Streaming
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/stream` | Master stream URL for an episode |
|
||||
| GET | `/api/servers` | Available servers for an episode |
|
||||
| GET | `/api/stream/resolve` | Resolve a streaming URL |
|
||||
| GET | `/api/stream/qualities` | Available quality variants |
|
||||
| GET | `/api/stream/proxy` | Proxied video stream |
|
||||
| GET | `/api/stream/ts-proxy` | Proxied TS segment stream |
|
||||
| GET | `/api/watch` | Watch page with stream data |
|
||||
| GET | `/api/download` | Download link for an episode |
|
||||
| GET | `/api/mapper-servers` | Server name mappings |
|
||||
|
||||
### Discovery
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/spotlight` | Featured/spotlight anime |
|
||||
| GET | `/api/trending` | Currently trending anime |
|
||||
| GET | `/api/top-ten` | Top 10 rankings |
|
||||
| GET | `/api/random` | Random anime recommendation |
|
||||
| GET | `/api/most-popular` | Most popular anime |
|
||||
| GET | `/api/trending-sidebar` | Trending sidebar widget data |
|
||||
|
||||
### Releases
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/new-release` | Recently released episodes |
|
||||
| GET | `/api/newly-added` | Newly added anime |
|
||||
| GET | `/api/latest-updated` | Latest updated anime |
|
||||
| GET | `/api/recently-updated` | Recently updated entries |
|
||||
| GET | `/api/completed` | Completed anime |
|
||||
| GET | `/api/upcoming` | Upcoming anime |
|
||||
|
||||
### Rankings
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/top-rankings` | Top ranked anime by category |
|
||||
|
||||
### Categories
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/genre/:name` | Anime by genre |
|
||||
| GET | `/api/type/:name` | Anime by type (TV, Movie, OVA, etc.) |
|
||||
| GET | `/api/status/:name` | Anime by status (Airing, Completed, etc.) |
|
||||
| GET | `/api/az-list/:letter` | Alphabetical listing |
|
||||
| GET | `/api/filter` | Multi-criteria filter |
|
||||
|
||||
### Schedule
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/schedule` | Anime release schedule |
|
||||
|
||||
### System
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/health` | Health check / uptime |
|
||||
| GET | `/api/stats` | API statistics |
|
||||
| GET | `/api/cache/stats` | Cache hit/miss statistics |
|
||||
| GET | `/api/mirrors` | List available mirror domains |
|
||||
| POST | `/api/mirrors/reset` | Reset failover mirror state |
|
||||
| GET | `/api/openapi` | OpenAPI/Swagger spec |
|
||||
|
||||
---
|
||||
|
||||
## // === ARCHITECTURE ===
|
||||
|
||||
```
|
||||
AniKotoAPI/
|
||||
├── api/ # Vercel serverless functions
|
||||
│ ├── index.js # Home endpoint
|
||||
│ ├── info.js # Anime info
|
||||
│ ├── search.js # Search
|
||||
│ ├── stream.js # Streaming
|
||||
│ └── ... # 38+ route handlers
|
||||
├── scrapers/ # Cheerio HTML scrapers
|
||||
│ ├── home.js
|
||||
│ ├── info.js
|
||||
│ ├── search.js
|
||||
│ └── ... # 28 scrapers
|
||||
├── utils/ # Shared utilities
|
||||
│ ├── cache.js # LRU cache with TTL
|
||||
│ ├── rateLimit.js # IP-based rate limiter
|
||||
│ ├── mirrors.js # Mirror failover logic
|
||||
│ └── compress.js # GZIP compression
|
||||
├── docs/ # Documentation
|
||||
│ ├── index.md # This file
|
||||
│ ├── endpoints.md # Full API reference
|
||||
│ ├── streaming.md # Streaming workflow
|
||||
│ ├── examples.md # Code examples
|
||||
│ ├── architecture.md # Design patterns
|
||||
│ └── testing.md # Test suite docs
|
||||
├── package.json
|
||||
└── vercel.json
|
||||
```
|
||||
|
||||
### Key Design Patterns
|
||||
|
||||
- **Scraping Layer**: 28 Cheerio-based scrapers parse HTML from anikototv.to, isolating page-specific logic from route handlers.
|
||||
- **Controller Layer**: 28 route handlers map HTTP requests to scraper calls, handle validation, and format responses.
|
||||
- **Cache Layer**: LRU cache with per-endpoint TTL reduces redundant scraping. Hot endpoints cache for 2–5 minutes; cold endpoints for 10+ minutes.
|
||||
- **Mirror Layer**: 5 source domains with automatic failover. If one domain is slow or down, requests transparently fall back to the next mirror.
|
||||
- **Rate Limiter**: Token bucket algorithm, 100 requests per 15-minute window per client IP.
|
||||
|
||||
---
|
||||
|
||||
## // === GETTING STARTED ===
|
||||
|
||||
### Using cURL
|
||||
|
||||
```bash
|
||||
# Get homepage data
|
||||
curl https://anikototvapi.vercel.app/api/
|
||||
|
||||
# Search for an anime
|
||||
curl "https://anikototvapi.vercel.app/api/search?q=one+piece"
|
||||
|
||||
# Get anime details
|
||||
curl "https://anikototvapi.vercel.app/api/info?link=/anime/one-piece"
|
||||
|
||||
# Get streaming servers
|
||||
curl "https://anikototvapi.vercel.app/api/servers?link=/one-piece-episode-1"
|
||||
|
||||
# Get trending anime
|
||||
curl https://anikototvapi.vercel.app/api/trending
|
||||
```
|
||||
|
||||
### Using JavaScript (fetch)
|
||||
|
||||
```javascript
|
||||
const BASE = "https://anikototvapi.vercel.app/api";
|
||||
|
||||
// Search
|
||||
const res = await fetch(`${BASE}/search?q=naruto`);
|
||||
const data = await res.json();
|
||||
console.log(data.results);
|
||||
```
|
||||
|
||||
### Using Python (requests)
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
BASE = "https://anikototvapi.vercel.app/api"
|
||||
|
||||
# Search
|
||||
r = requests.get(f"{BASE}/search?q=naruto")
|
||||
print(r.json()["results"])
|
||||
```
|
||||
|
||||
### Using Node.js (axios)
|
||||
|
||||
```javascript
|
||||
const axios = require("axios");
|
||||
const BASE = "https://anikototvapi.vercel.app/api";
|
||||
|
||||
async function searchAnime(query) {
|
||||
const { data } = await axios.get(`${BASE}/search`, {
|
||||
params: { q: query }
|
||||
});
|
||||
return data.results;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## // === RATE LIMITING ===
|
||||
|
||||
- **Limit**: 100 requests per 15-minute window
|
||||
- **Scope**: Per client IP address
|
||||
- **Headers**: Rate limit info returned in response headers
|
||||
- **Exceeded**: Returns `429 Too Many Requests`
|
||||
|
||||
If you hit the rate limit, wait for the window to reset before retrying.
|
||||
|
||||
---
|
||||
|
||||
## // === MIRROR FAILOVER ===
|
||||
|
||||
AniKotoAPI maintains 5 mirror domains. When a request fails on the primary domain, the system automatically retries on the next available mirror.
|
||||
|
||||
```
|
||||
Primary → Mirror 1 → Mirror 2 → Mirror 3 → Mirror 4 → Mirror 5
|
||||
```
|
||||
|
||||
Use `/api/mirrors` to check current mirror status, or `POST /api/mirrors/reset` to reset the failover state.
|
||||
|
||||
---
|
||||
|
||||
## // === CACHING ===
|
||||
|
||||
The API uses an LRU (Least Recently Used) cache with per-endpoint TTL:
|
||||
|
||||
| Endpoint Category | TTL |
|
||||
|-------------------|-----|
|
||||
| Home / Spotlight | 2 minutes |
|
||||
| Search | 3 minutes |
|
||||
| Anime Info | 5 minutes |
|
||||
| Streaming | 1 minute |
|
||||
| Rankings / Lists | 10 minutes |
|
||||
|
||||
Cache stats available at `/api/cache/stats`.
|
||||
|
||||
---
|
||||
|
||||
## // === ERROR RESPONSES ===
|
||||
|
||||
All errors return JSON with a consistent structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": true,
|
||||
"message": "Description of what went wrong",
|
||||
"status": 404
|
||||
}
|
||||
```
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| 400 | Bad request / missing parameters |
|
||||
| 404 | Resource not found |
|
||||
| 429 | Rate limit exceeded |
|
||||
| 500 | Internal server error |
|
||||
|
||||
---
|
||||
|
||||
## // === DOCUMENTATION ===
|
||||
|
||||
| File | Description |
|
||||
|------|-------------|
|
||||
| [endpoints.md](./endpoints.md) | Full API reference for all 38+ endpoints |
|
||||
| [streaming.md](./streaming.md) | Complete streaming workflow guide |
|
||||
| [examples.md](./examples.md) | Working code examples in cURL, JS, Python |
|
||||
| [architecture.md](./architecture.md) | Project structure and design patterns |
|
||||
| [testing.md](./testing.md) | Integration test suite documentation |
|
||||
|
||||
---
|
||||
|
||||
## // === CONTRIBUTING ===
|
||||
|
||||
Contributions are welcome. To contribute:
|
||||
|
||||
1. Fork the repository from [GitHub](https://github.com/Shineii86/AniKotoAPI)
|
||||
2. Create a feature branch: `git checkout -b feature/my-feature`
|
||||
3. Make your changes and test them
|
||||
4. Commit with a clear message
|
||||
5. Push and open a Pull Request
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/Shineii86/AniKotoAPI.git
|
||||
cd AniKotoAPI
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Follow existing code style and patterns
|
||||
- Add scrapers in `scrapers/` for new pages
|
||||
- Add route handlers in `api/` for new endpoints
|
||||
- Update documentation when adding features
|
||||
- Test all changes before submitting
|
||||
|
||||
---
|
||||
|
||||
## // === LICENSE ===
|
||||
|
||||
This project is licensed under the **MIT License**.
|
||||
|
||||
```
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024 Shinei Nouzen
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## // === LINKS ===
|
||||
|
||||
- **Live API**: https://anikototvapi.vercel.app/api
|
||||
- **GitHub**: https://github.com/Shineii86/AniKotoAPI
|
||||
- **OpenAPI Spec**: https://anikototvapi.vercel.app/api/openapi
|
||||
- **Health Check**: https://anikototvapi.vercel.app/api/health
|
||||
- **Author**: [Shinei Nouzen](https://github.com/Shineii86)
|
||||
|
||||
---
|
||||
|
||||
// ══════ END: index.md ══════
|
||||
+787
-242
File diff suppressed because it is too large
Load Diff
@@ -5,7 +5,7 @@
|
||||
*
|
||||
* @description
|
||||
* Controller for top anime rankings. Returns ranked anime list
|
||||
* with support for top (all-time) and newest sort modes.
|
||||
* with support for day, week, and month sort modes.
|
||||
*
|
||||
* @exports
|
||||
* getTopAnimeRankings - Express route handler for GET /api/top-rankings
|
||||
@@ -28,18 +28,18 @@ import { getCache, setCache, TTL } from "../helper/cache.helper.js";
|
||||
* with support for top (all-time) and newest sort modes.
|
||||
*
|
||||
* @param {object} req - Express request object
|
||||
* @param {string} [req.query.sort="top"] - Sort mode: "top" or "newest"
|
||||
* @param {string} [req.query.sort="day"] - Sort mode: "day", "week", or "month"
|
||||
* @param {object} res - Express response object
|
||||
* @param {Function} next - Express next middleware function
|
||||
* @returns {void} Sends JSON response with ranked anime list
|
||||
*
|
||||
* @example
|
||||
* GET /api/top-rankings?sort=top
|
||||
* GET /api/top-rankings?sort=day
|
||||
* Response: { success: true, results: [{ rank: 1, title: "...", ... }] }
|
||||
*/
|
||||
const getTopAnimeRankings = async (req, res, next) => {
|
||||
try {
|
||||
const { sort = "top" } = req.query;
|
||||
const { sort = "day" } = req.query;
|
||||
const cacheKey = `top_rankings_${sort}`;
|
||||
const cached = getCache(cacheKey);
|
||||
if (cached) {
|
||||
|
||||
@@ -61,7 +61,8 @@ const extractEpisodeList = async (slugOrId) => {
|
||||
headers: { "X-Requested-With": "XMLHttpRequest" }
|
||||
});
|
||||
|
||||
const ajaxHtml = typeof ajaxRaw === "string" ? ajaxRaw : (ajaxRaw?.result || "");
|
||||
const ajaxParsed = typeof ajaxRaw === "string" ? JSON.parse(ajaxRaw) : ajaxRaw;
|
||||
const ajaxHtml = ajaxParsed?.result || "";
|
||||
const $ep = cheerio.load(ajaxHtml);
|
||||
|
||||
const episodes = [];
|
||||
|
||||
@@ -55,7 +55,8 @@ const extractEpisodeListAjax = async (animeId, style = "", vrf = "") => {
|
||||
});
|
||||
|
||||
// NOTE: Response is JSON {status, result} where result is HTML
|
||||
const html = typeof raw === "string" ? raw : (raw?.result || "");
|
||||
const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
|
||||
const html = parsed?.result || "";
|
||||
const $ = cheerio.load(html);
|
||||
|
||||
// NOTE: Extract filter options (Sub/Dub, episode ranges)
|
||||
|
||||
@@ -661,7 +661,7 @@ app.get("/api/openapi", (req, res) => {
|
||||
"/az-list/{letter}": { get: { summary: "A-Z listing", tags: ["Discovery"] } },
|
||||
"/suggestions": { get: { summary: "Anime suggestions", tags: ["Search"] } },
|
||||
"/upcoming": { get: { summary: "Upcoming anime", tags: ["Discovery"] } },
|
||||
"/top-rankings": { get: { summary: "Top anime rankings (top/newest)", tags: ["Rankings"] } },
|
||||
"/top-rankings": { get: { summary: "Top anime rankings (day/week/month)", tags: ["Rankings"] } },
|
||||
"/recently-updated": { get: { summary: "Recently updated (all/dub/sub tabs)", tags: ["Releases"] } },
|
||||
"/completed": { get: { summary: "Completed anime series", tags: ["Rankings"] } },
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user