256 lines
14 KiB
Python
256 lines
14 KiB
Python
# coding: utf-8
|
|
|
|
"""
|
|
PeerTube
|
|
|
|
The PeerTube API is built on HTTP(S) and is RESTful. You can use your favorite HTTP/REST library for your programming language to use PeerTube. The spec API is fully compatible with [openapi-generator](https://github.com/OpenAPITools/openapi-generator/wiki/API-client-generator-HOWTO) which generates a client SDK in the language of your choice - we generate some client SDKs automatically: - [Python](https://framagit.org/framasoft/peertube/clients/python) - [Go](https://framagit.org/framasoft/peertube/clients/go) - [Kotlin](https://framagit.org/framasoft/peertube/clients/kotlin) See the [REST API quick start](https://docs.joinpeertube.org/api/rest-getting-started) for a few examples of using the PeerTube API. # Authentication When you sign up for an account on a PeerTube instance, you are given the possibility to generate sessions on it, and authenticate there using an access token. Only __one access token can currently be used at a time__. ## Roles Accounts are given permissions based on their role. There are three roles on PeerTube: Administrator, Moderator, and User. See the [roles guide](https://docs.joinpeertube.org/admin/managing-users#roles) for a detail of their permissions. # Errors The API uses standard HTTP status codes to indicate the success or failure of the API call, completed by a [RFC7807-compliant](https://tools.ietf.org/html/rfc7807) response body. ``` HTTP 1.1 404 Not Found Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Video not found\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"status\": 404, \"title\": \"Not Found\", \"type\": \"about:blank\" } ``` We provide error `type` values for [a growing number of cases](https://github.com/Chocobozzz/PeerTube/blob/develop/packages/models/src/server/core-error-code.enum.ts), but it is still optional. Types are used to disambiguate errors that bear the same status code and are non-obvious: ``` HTTP 1.1 403 Forbidden Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Cannot get this video regarding follow constraints\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"status\": 403, \"title\": \"Forbidden\", \"type\": \"https://docs.joinpeertube.org/api-rest-reference.html#section/Errors/does_not_respect_follow_constraints\" } ``` Here a 403 error could otherwise mean that the video is private or blocklisted. ### Validation errors Each parameter is evaluated on its own against a set of rules before the route validator proceeds with potential testing involving parameter combinations. Errors coming from validation errors appear earlier and benefit from a more detailed error description: ``` HTTP 1.1 400 Bad Request Content-Type: application/problem+json; charset=utf-8 { \"detail\": \"Incorrect request parameters: id\", \"docs\": \"https://docs.joinpeertube.org/api-rest-reference.html#operation/getVideo\", \"instance\": \"/api/v1/videos/9c9de5e8-0a1e-484a-b099-e80766180\", \"invalid-params\": { \"id\": { \"location\": \"params\", \"msg\": \"Invalid value\", \"param\": \"id\", \"value\": \"9c9de5e8-0a1e-484a-b099-e80766180\" } }, \"status\": 400, \"title\": \"Bad Request\", \"type\": \"about:blank\" } ``` Where `id` is the name of the field concerned by the error, within the route definition. `invalid-params.<field>.location` can be either 'params', 'body', 'header', 'query' or 'cookies', and `invalid-params.<field>.value` reports the value that didn't pass validation whose `invalid-params.<field>.msg` is about. ### Deprecated error fields Some fields could be included with previous versions. They are still included but their use is deprecated: - `error`: superseded by `detail` - `code`: superseded by `type` (which is now an URI) # Rate limits We are rate-limiting all endpoints of PeerTube's API. Custom values can be set by administrators: | Endpoint (prefix: `/api/v1`) | Calls | Time frame | |------------------------------|---------------|--------------| | `/*` | 50 | 10 seconds | | `POST /users/token` | 15 | 5 minutes | | `POST /users/register` | 2<sup>*</sup> | 5 minutes | | `POST /users/ask-send-verify-email` | 3 | 5 minutes | Depending on the endpoint, <sup>*</sup>failed requests are not taken into account. A service limit is announced by a `429 Too Many Requests` status code. You can get details about the current state of your rate limit by reading the following headers: | Header | Description | |-------------------------|------------------------------------------------------------| | `X-RateLimit-Limit` | Number of max requests allowed in the current time period | | `X-RateLimit-Remaining` | Number of remaining requests in the current time period | | `X-RateLimit-Reset` | Timestamp of end of current time period as UNIX timestamp | | `Retry-After` | Seconds to delay after the first `429` is received | # CORS This API features [Cross-Origin Resource Sharing (CORS)](https://fetch.spec.whatwg.org/), allowing cross-domain communication from the browser for some routes: | Endpoint | |------------------------- ---| | `/api/*` | | `/download/*` | | `/lazy-static/*` | | `/.well-known/webfinger` | In addition, all routes serving ActivityPub are CORS-enabled for all origins.
|
|
|
|
The version of the OpenAPI document: 5.2.0
|
|
Generated by OpenAPI Generator (https://openapi-generator.tech)
|
|
|
|
Do not edit the class manually.
|
|
""" # noqa: E501
|
|
|
|
|
|
import io
|
|
import json
|
|
import re
|
|
import ssl
|
|
|
|
import urllib3
|
|
|
|
from peertube.exceptions import ApiException, ApiValueError
|
|
|
|
SUPPORTED_SOCKS_PROXIES = {"socks5", "socks5h", "socks4", "socks4a"}
|
|
RESTResponseType = urllib3.HTTPResponse
|
|
|
|
|
|
def is_socks_proxy_url(url):
|
|
if url is None:
|
|
return False
|
|
split_section = url.split("://")
|
|
if len(split_section) < 2:
|
|
return False
|
|
else:
|
|
return split_section[0].lower() in SUPPORTED_SOCKS_PROXIES
|
|
|
|
|
|
class RESTResponse(io.IOBase):
|
|
|
|
def __init__(self, resp) -> None:
|
|
self.response = resp
|
|
self.status = resp.status
|
|
self.reason = resp.reason
|
|
self.data = None
|
|
|
|
def read(self):
|
|
if self.data is None:
|
|
self.data = self.response.data
|
|
return self.data
|
|
|
|
def getheaders(self):
|
|
"""Returns a dictionary of the response headers."""
|
|
return self.response.headers
|
|
|
|
def getheader(self, name, default=None):
|
|
"""Returns a given response header."""
|
|
return self.response.headers.get(name, default)
|
|
|
|
|
|
class RESTClientObject:
|
|
|
|
def __init__(self, configuration) -> None:
|
|
# urllib3.PoolManager will pass all kw parameters to connectionpool
|
|
# https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/poolmanager.py#L75 # noqa: E501
|
|
# https://github.com/shazow/urllib3/blob/f9409436f83aeb79fbaf090181cd81b784f1b8ce/urllib3/connectionpool.py#L680 # noqa: E501
|
|
# Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html # noqa: E501
|
|
|
|
# cert_reqs
|
|
if configuration.verify_ssl:
|
|
cert_reqs = ssl.CERT_REQUIRED
|
|
else:
|
|
cert_reqs = ssl.CERT_NONE
|
|
|
|
pool_args = {
|
|
"cert_reqs": cert_reqs,
|
|
"ca_certs": configuration.ssl_ca_cert,
|
|
"cert_file": configuration.cert_file,
|
|
"key_file": configuration.key_file,
|
|
}
|
|
if configuration.assert_hostname is not None:
|
|
pool_args['assert_hostname'] = (
|
|
configuration.assert_hostname
|
|
)
|
|
|
|
if configuration.retries is not None:
|
|
pool_args['retries'] = configuration.retries
|
|
|
|
if configuration.tls_server_name:
|
|
pool_args['server_hostname'] = configuration.tls_server_name
|
|
|
|
|
|
if configuration.socket_options is not None:
|
|
pool_args['socket_options'] = configuration.socket_options
|
|
|
|
if configuration.connection_pool_maxsize is not None:
|
|
pool_args['maxsize'] = configuration.connection_pool_maxsize
|
|
|
|
# https pool manager
|
|
self.pool_manager: urllib3.PoolManager
|
|
|
|
if configuration.proxy:
|
|
if is_socks_proxy_url(configuration.proxy):
|
|
from urllib3.contrib.socks import SOCKSProxyManager
|
|
pool_args["proxy_url"] = configuration.proxy
|
|
pool_args["headers"] = configuration.proxy_headers
|
|
self.pool_manager = SOCKSProxyManager(**pool_args)
|
|
else:
|
|
pool_args["proxy_url"] = configuration.proxy
|
|
pool_args["proxy_headers"] = configuration.proxy_headers
|
|
self.pool_manager = urllib3.ProxyManager(**pool_args)
|
|
else:
|
|
self.pool_manager = urllib3.PoolManager(**pool_args)
|
|
|
|
def request(
|
|
self,
|
|
method,
|
|
url,
|
|
headers=None,
|
|
body=None,
|
|
post_params=None,
|
|
_request_timeout=None
|
|
):
|
|
"""Perform requests.
|
|
|
|
:param method: http request method
|
|
:param url: http request url
|
|
:param headers: http request headers
|
|
:param body: request json body, for `application/json`
|
|
:param post_params: request post parameters,
|
|
`application/x-www-form-urlencoded`
|
|
and `multipart/form-data`
|
|
:param _request_timeout: timeout setting for this request. If one
|
|
number provided, it will be total request
|
|
timeout. It can also be a pair (tuple) of
|
|
(connection, read) timeouts.
|
|
"""
|
|
method = method.upper()
|
|
assert method in [
|
|
'GET',
|
|
'HEAD',
|
|
'DELETE',
|
|
'POST',
|
|
'PUT',
|
|
'PATCH',
|
|
'OPTIONS'
|
|
]
|
|
|
|
if post_params and body:
|
|
raise ApiValueError(
|
|
"body parameter cannot be used with post_params parameter."
|
|
)
|
|
|
|
post_params = post_params or {}
|
|
headers = headers or {}
|
|
|
|
timeout = None
|
|
if _request_timeout:
|
|
if isinstance(_request_timeout, (int, float)):
|
|
timeout = urllib3.Timeout(total=_request_timeout)
|
|
elif (
|
|
isinstance(_request_timeout, tuple)
|
|
and len(_request_timeout) == 2
|
|
):
|
|
timeout = urllib3.Timeout(
|
|
connect=_request_timeout[0],
|
|
read=_request_timeout[1]
|
|
)
|
|
|
|
try:
|
|
# For `POST`, `PUT`, `PATCH`, `OPTIONS`, `DELETE`
|
|
if method in ['POST', 'PUT', 'PATCH', 'OPTIONS', 'DELETE']:
|
|
|
|
# no content type provided or payload is json
|
|
content_type = headers.get('Content-Type')
|
|
if (
|
|
not content_type
|
|
or re.search('json', content_type, re.IGNORECASE)
|
|
):
|
|
request_body = None
|
|
if body is not None:
|
|
request_body = json.dumps(body)
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
body=request_body,
|
|
timeout=timeout,
|
|
headers=headers,
|
|
preload_content=False
|
|
)
|
|
elif content_type == 'application/x-www-form-urlencoded':
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
fields=post_params,
|
|
encode_multipart=False,
|
|
timeout=timeout,
|
|
headers=headers,
|
|
preload_content=False
|
|
)
|
|
elif content_type == 'multipart/form-data':
|
|
# must del headers['Content-Type'], or the correct
|
|
# Content-Type which generated by urllib3 will be
|
|
# overwritten.
|
|
del headers['Content-Type']
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
fields=post_params,
|
|
encode_multipart=True,
|
|
timeout=timeout,
|
|
headers=headers,
|
|
preload_content=False
|
|
)
|
|
# Pass a `string` parameter directly in the body to support
|
|
# other content types than JSON when `body` argument is
|
|
# provided in serialized form.
|
|
elif isinstance(body, str) or isinstance(body, bytes):
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
body=body,
|
|
timeout=timeout,
|
|
headers=headers,
|
|
preload_content=False
|
|
)
|
|
elif headers['Content-Type'] == 'text/plain' and isinstance(body, bool):
|
|
request_body = "true" if body else "false"
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
body=request_body,
|
|
preload_content=False,
|
|
timeout=timeout,
|
|
headers=headers)
|
|
else:
|
|
# Cannot generate the request from given parameters
|
|
msg = """Cannot prepare a request message for provided
|
|
arguments. Please check that your arguments match
|
|
declared content type."""
|
|
raise ApiException(status=0, reason=msg)
|
|
# For `GET`, `HEAD`
|
|
else:
|
|
r = self.pool_manager.request(
|
|
method,
|
|
url,
|
|
fields={},
|
|
timeout=timeout,
|
|
headers=headers,
|
|
preload_content=False
|
|
)
|
|
except urllib3.exceptions.SSLError as e:
|
|
msg = "\n".join([type(e).__name__, str(e)])
|
|
raise ApiException(status=0, reason=msg)
|
|
|
|
return RESTResponse(r)
|