add api docs

This commit is contained in:
simon 2023-04-08 20:25:56 +07:00
parent 1b37761979
commit 62c2a5da6f
No known key found for this signature in database
GPG Key ID: 2C15AA5E89985DD4
10 changed files with 438 additions and 2 deletions

View File

@ -0,0 +1,141 @@
# Additional API endpoints
## Login
Return token and user ID for username and password:
**POST** `/api/login/`
```json
{
"username": "tubearchivist",
"password": "verysecret"
}
```
after successful login returns
```json
{
"token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"user_id": 1
}
```
## Refresh
**GET** `/api/refresh/`
Parameters:
- **type**: one of *video*, *channel*, *playlist*, optional
- **id**: item id, optional
without specifying type: return total for all queued items:
```json
{
"total_queued": 2,
"type": "all",
"state": "running"
}
```
specify type: return total items queue of this type:
```json
{
"total_queued": 2,
"type": "video",
"state": "running"
}
```
specify type *and* id to get state of item in queue:
```json
{
"total_queued": 2,
"type": "video",
"state": "in_queue",
"id": "video-id"
}
```
**POST** `/api/refresh/`
Parameter:
- extract_videos: to refresh all videos for channels/playlists, default False
Manually start a refresh task: post list of *video*, *channel*, *playlist* IDs:
```json
{
"video": ["video1", "video2", "video3"],
"channel": ["channel1", "channel2", "channel3"],
"playlist": ["playlist1", "playlist2"]
}
```
## Cookie
Check your youtube cookie settings, *status* turns to `true` if cookie has been validated.
**GET** `/api/cookie/`
```json
{
"cookie_enabled": true,
"status": true,
"validated": 1680953715,
"validated_str": "timestamp"
}
```
**POST** `/api/cookie/`
Send empty post request to validate cookie.
```json
{
"cookie_validated": true
}
```
**PUT** `/api/cookie/`
Send put request containing the cookie as a string:
```json
{
"cookie": "your-cookie-as-string"
}
```
Imports and validates cookie, returns on success:
```json
{
"cookie_import": "done",
"cookie_validated": true
}
```
Or returns status code 400 on failure:
```json
{
"cookie_import": "fail",
"cookie_validated": false
}
```
## Search
**GET** `/api/search/?query=<query>`
Returns search results from your query.
## Watched
**POST** `/api/watched/`
Change watched state, where the `id` can be a single video, or channel/playlist to change all videos belonging to that channel/playlist.
```json
{
"id": "xxxxxxx",
"is_watched": true
}
```
## Ping
Validate your connection with the API
**GET** `/api/ping/`
When valid returns message with user id:
```json
{
"response": "pong",
"user": 1
}
```

View File

@ -0,0 +1,27 @@
# Channel
## Channel List
`/api/channel/`
Parameter:
- filter: subscribed
Subscribe to a list of channels:
**POST** `/api/channel/`
```json
{
"data": [
{"channel_id": "UC9-y-6csu5WGm29I7JiwpnA", "channel_subscribed": true}
]
}
```
## Channel Item
**GET** `/api/channel/<channel_id>/`
**DELETE** `/api/channel/\<channel_id>/`
- Will delete channel with all it's videos
## Channel Videos
**GET** /api/channel/\<channel_id>/video/

View File

@ -0,0 +1,51 @@
# Download
## Download Queue List
**GET** `/api/download/`
Parameter:
- filter: pending, ignore
- channel: channel-id
Add list of videos to download queue:
**POST** `/api/download/`
```json
{
"data": [
{"youtube_id": "NYj3DnI81AQ", "status": "pending"}
]
}
```
Delete download queue items by filter:
**DELETE** `/api/download/?filter=ignore`
**DELETE** `/api/download/?filter=pending`
## Download Queue Item
**GET** `/api/download/<video_id>/`
**POST** `/api/download/<video_id>/`
Ignore video in download queue:
```json
{
"status": "ignore"
}
```
Add to queue previously ignored video:
```json
{
"status": "pending"
}
```
Download existing video now:
```json
{
"status": "priority"
}
```
**DELETE** `/api/download/<video_id>/`
Forget or delete from download queue

View File

@ -0,0 +1,43 @@
# Introduction
This page has a generic overview with how the Tube Archivist API functions. This is the place to start.
!!! note
These API endpoints *have* changed in the past and *will* change again while building out additional integrations and functionality. For the time being, don't expect backwards compatibility for third party integrations using these endpoints.
## Context
- All changes to the API are marked with a `[API]` keyword for easy searching, for example search for [commits](https://github.com/tubearchivist/tubearchivist/search?o=desc&q=%5Bapi%5D&s=committer-date&type=commits). You'll find the same in the [release notes](https://github.com/tubearchivist/tubearchivist/releases).
- Check the commit history and release notes to see if a documented feature is already in your release. The documentation might be ahead of the regular release schedule.
## Authentication
API token will get automatically created, accessible on the settings page. Token needs to be passed as an authorization header with every request. Additionally session based authentication is enabled too: When you are logged into your TubeArchivist instance, you'll have access to the api in the browser for testing.
Curl example:
```shell
curl -v /api/video/<video-id>/ \
-H "Authorization: Token xxxxxxxxxx"
```
Python requests example:
```python
import requests
url = "/api/video/<video-id>/"
headers = {"Authorization": "Token xxxxxxxxxx"}
response = requests.get(url, headers=headers)
```
## Pagination
The list views return a paginate object with the following keys:
- page_size: *int* current page size set in config
- page_from: *int* first result idx
- prev_pages: *array of ints* of previous pages, if available
- current_page: *int* current page from query
- max_hits: *bool* if max of 10k results is reached
- params: *str* additional url encoded query parameters
- last_page: *int* of last page link
- next_pages: *array of ints* of next pages
- total_hits: *int* total results
Pass page number as a query parameter: `page=2`. Defaults to *0*, `page=1` is redundant and falls back to *0*. If a page query doesn't return any results, you'll get `HTTP 404 Not Found`.

View File

@ -0,0 +1,10 @@
# Playlist
## Playlist List
**GET** `/api/playlist/`
## Playlist Item
**GET** `/api/playlist/<playlist_id>/`
## Playlist Videos
**GET** `/api/playlist/<playlist_id>/video/`

View File

@ -0,0 +1,43 @@
# Snapshot
## Snapshot List
**GET** `/api/snapshot/`
Return snapshot config and a list of available snapshots.
```json
{
"next_exec": epoch,
"next_exec_str": "date_str",
"expire_after": "30d",
"snapshots": []
}
```
**POST** `/api/snapshot/`
Create new snapshot now, will return immediately, task will run async in the background, returns snapshot name:
```json
{
"snapshot_name": "ta_daily_<random-id>"
}
```
## Snapshot Item View
**GET** `/api/snapshot/<snapshot-id>/`
Return metadata of a single snapshot
```json
{
"id": "ta_daily_<random-id>",
"state": "SUCCESS",
"es_version": "0.0.0",
"start_date": "date_str",
"end_date": "date_str",
"end_stamp": epoch,
"duration_s": 0
}
```
**POST** `/api/snapshot/<snapshot-id>/`
Restore this snapshot
**DELETE** `/api/snapshot/<snapshot-id>/`
Remove this snapshot from index

24
mkdocs/docs/api/task.md Normal file
View File

@ -0,0 +1,24 @@
# Task Name and Task ID
## Task Name List View
**GET** `/api/task-name/`
Return all task results.
## Task Name Item View
**GET** `/api/task-name/<task-name>/`
Return all ask results by task name
**POST** `/api/task-name/<task-name>/`
Start a new task by task name, only tasks without arguments can be started like that, see `home.tasks.BaseTask.TASK_CONFIG` for more info.
## Task ID view
**GET** `/api/task-id/<task-id>/`
Return task status by task ID
**POST** `/api/task-id/<task-id>/`
```json
{
"command": "stop|kill"
}
```
Send command to a task, valid commands: `stop` and `kill`. Not all tasks implement these commands `home.tasks.BaseTask.TASK_CONFIG` for details.

78
mkdocs/docs/api/video.md Normal file
View File

@ -0,0 +1,78 @@
# Video
## Video List
**GET** `/api/video/`
## Video Item
**GET** `/api/video/<video_id>/`
**DELETE** `/api/video/<video_id>/`
## Video Comment
**GET** `/api/video/<video_id>/comment/`
## Video Similar
**GET** `/api/video/<video_id>/similar/`
## Video Progress
`/api/video/<video_id>/progress/`
Progress is stored for each user.
Get last player position of a video:
**GET** `/api/video/<video_id>/progress/`
```json
{
"youtube_id": "<video_id>",
"user_id": 1,
"position": 100
}
```
Update player position of video:
**POST** `/api/video/<video_id>/progress/`
```json
{
"position": 100
}
```
Delete player position:
**DELETE** `/api/video/<video_id>/progress/`
## Sponsor Block
`/api/video/<video_id>/sponsor/`
Integrate with sponsorblock
Get list of segments:
**GET** `/api/video/<video_id>/sponsor/`
!!! note
Writing to Sponsorblock enpoints is only simulated for now and won't forward any requests. This needs some clever UI/UX implementation first.
Vote on existing segment:
**POST** `/api/video/<video_id>/sponsor/`
```json
{
"vote": {
"uuid": "<uuid>",
"yourVote": 1
}
}
```
yourVote needs to be *int*: 0 for downvote, 1 for upvote, 20 to undo vote
Create new segment
**POST** `/api/video/<video_id>/sponsor/`
```json
{
"segment": {
"startTime": 5,
"endTime": 10
}
}
```
Timestamps either *int* or *float*, end time can't be before start time.

View File

@ -10,12 +10,17 @@
font-family: 'Sen-Regular';
}
* {
p, a, span, h3 {
font-family: Sen-Regular;
}
code span {
font-family: monospace;
}
h1,
h2 {
h2,
strong {
font-family: Sen-Bold;
}
@ -50,6 +55,11 @@ footer {
--md-admonition-bg-color: var(--highlight-bg);
--md-admonition-fg-color: var(--main-font);
--md-footer-bg-color: var(--highlight-bg);
--md-code-hl-punctuation-color: var(--main-font);
--md-code-hl-name-color: var(--accent-font-light);
--md-code-hl-string-color: var(--accent-font-dark);
--md-code-hl-number-color: var(--highlight-error-light);
--md-code-hl-operator-color: var(--highlight-error);
}
:root {

View File

@ -21,6 +21,15 @@ nav:
- Configuration:
- 'LDAP Authentication': 'configuration/ldap.md'
- 'Cast Support': 'configuration/cast.md'
- API:
- 'Introduction': 'api/introduction.md'
- 'Video': 'api/video.md'
- 'Channel': 'api/channel.md'
- 'Playlist': 'api/playlist.md'
- 'Download': 'api/download.md'
- 'Snapshot': 'api/snapshot.md'
- 'Task': 'api/task.md'
- 'Additional': 'api/additional.md'
- Links:
- 'Main site': https://www.tubearchivist.com
- 'Join us on Discord!': https://www.tubearchivist.com/discord