jasima/majuna
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: refactor redirector docs into api docs

Browse source
This commit is contained in:
Iain Learmonth 2024-11-09 11:11:11 +00:00
parent 73439a8121
commit c795a70d80
7 changed files with 48 additions and 158 deletions
Download patch file Download diff file Expand all files Collapse all files

0
docs/admin/redirector/config.rst → docs/admin/api/config.rst
View file

4
docs/admin/redirector/index.rst → docs/admin/api/index.rst
View file

@ -32,8 +32,6 @@ This documentation is structured into the following sections:
1. :doc:`Installation <install>`: Provides instructions for installing and setting up the Short Link Redirector application.
2. :doc:`Configuration <config>`: Explains the configuration options and how to customize the application's behavior.
3. :doc:`HTTP API Reference <http>`: Details the available HTTP API endpoints and their usage.
4. :doc:`Command-Line Interface (CLI) <cli>`: Describes the command-line interface commands and their functionality.
We recommend reading through the documentation sequentially to gain a comprehensive understanding of the application and its features.
@ -44,5 +42,3 @@ We recommend reading through the documentation sequentially to gain a comprehens
install
config
http
cli

0
docs/admin/redirector/install.rst → docs/admin/api/install.rst
View file

96
docs/admin/redirector/cli.rst
View file

@ -1,96 +0,0 @@
===============
CLI Interface
===============
Introduction
------------
The CLI interface provides command-line tools for manual short link administration. These tools allow users to perform various operations, such as generating short links, resolving short links, and looking up country information using GeoIP.
Available Commands
------------------
The following commands are available in the CLI:
.. list-table::
:header-rows: 1
* - Command
- Description
* - short
- Generate a short link.
* - direct
- Generate a direct mirror link.
* - resolve
- Resolve a short link to a mirror link.
* - geoip
- Look up the country name for an IP address.
Command: short
^^^^^^^^^^^^^
Generate a short link.
Command Usage:
.. code-block:: shell
$ link short <url>
Arguments:
- `url` (required): The URL for which a short link needs to be generated.
Command: direct
^^^^^^^^^^^^^^
Generate a direct mirror link.
Command Usage:
.. code-block:: shell
$ link direct <url>
Arguments:
- `url` (required): The URL for which a direct mirror link needs to be generated.
Command: resolve
^^^^^^^^^^^^^^^^
Resolve a short link to a mirror link.
Command Usage:
.. code-block:: shell
$ link resolve <hash>
Arguments:
- `hash` (required): The hash associated with the short link.
Command: geoip
^^^^^^^^^^^^^^
Look up the country name for an IP address.
Command Usage:
.. code-block:: shell
$ link geoip <ip>
Arguments:
- `ip` (required): The IP address for which the country name needs to be looked up.
Configuration
-------------
The CLI interface uses the application's configuration file to load settings and defaults. See :doc:`configuration file <config>` for more information.
Environment Variables
---------------------
The application supports the following environment variables to configure its behavior:
- `REDIRECTOR_BASE_URL`: The base URL used for generating short links and direct mirror links. If not set, it defaults to `http://127.0.0.1:5000/`.
- `REDIRECTOR_API_KEY`: The API key used for generating short links and direct mirror links. If not set, it defaults to `None`.

7
docs/admin/redirector/dev.rst
View file

@ -1,7 +0,0 @@
===================
Developer Reference
===================
.. automodule:: app
:members:

158
docs/admin/redirector/http.rst
View file

@ -1,158 +0,0 @@
============
HTTP API
============
Introduction
------------
The HTTP API allows clients to interact with the application and perform various operations related to short links and mirrors. The API supports the following endpoints:
.. list-table::
:header-rows: 1
* - Endpoint
- Method
- Description
* - /me
- GET
- Retrieve information about the authenticated user's pool.
* - /link
- GET
- Generate a short link or a direct mirror link.
* - /updt
- POST
- Update the application's data.
* - /<hash>
- GET
- Redirect to the original URL associated with the given hash.
Authentication
--------------
The API endpoints are protected by authentication. The authentication method depends on the endpoint:
- /me endpoint: The API key is provided in the request arguments using the `key` parameter. If no API key is provided, the "public" resource pool is used.
- /link endpoint: The API key is provided in the request arguments using the `key` parameter. If no API key is provided, the "public" resource pool is used.
- /updt endpoint: The API key is sent in the `Authorization` header as a bearer token.
Endpoints
---------
/me
^^^^^^
Retrieve information about the authenticated user's pool.
- Method: GET
- URL: /me
Query Parameters:
- `key` (optional): The API key of the pool. If not provided, the public API key is used.
Response:
- Success: Returns the information about the pool in JSON format.
- Failure: Returns a 403 response if the API key is invalid.
/link
^^^^^
Generate a short link or a direct mirror link.
- Method: GET
- URL: /link
Query Parameters:
- `url` (required): The URL for which a link needs to be generated.
- `type` (optional): The type of link to generate. Valid values are "direct", "short", or "getsitecopy". If not provided, "direct" is used.
- `key` (optional): The API key of the pool. If not provided, the public API key is used.
- `expiry` (optional): The duration that a GetSiteCopy article will remain published for. Valid values are "long" and "short". If not provided, "short" is used.
- `footer_text` (optional): Defines the footer text to be used when publishing a GetSiteCopy article.
- `footer_link` (optional): Defines the footer link to be used when publishing a GetSiteCopy article.
When neither `footer_text` or `footer_link` are specified, if a mirror link is available to the site's homepage, this will be used for the footer link.
Response:
- Success: Returns the generated link in JSON format.
- Failure: Returns a 404 response if a link could not be generated.
/updt
^^^^^
Update the application's data.
- Method: POST
- URL: /updt
Headers:
- `Authorization`: The API key as a bearer token.
Request Body:
- The updated data in JSON format.
Response:
- Success: Returns a JSON response indicating the update was successful.
- Failure: Returns a 403 response if the API key is invalid.
/<hash>
^^^^^^^
Redirect to the original URL associated with the given hash.
- Method: GET
- URL: /<hash>
Path Parameters:
- `hash` (required): The hash associated with the short link.
Query Parameters:
- `force` (optional): Always redirect to a mirror and ignore GeoIP information.
- `force_ip` (optional): Override the client IP address and base the GeoIP lookup on this IP address instead.
Response:
- Success: Redirects the client to the original URL.
- Failure: Returns a 404 response if the hash is invalid or not found.
Example Usage
-------------
.. code-block:: bash
$ curl -X GET /me?key=<api_key>
$ curl -X GET /link?url=<url>&type=<type>&key=<api_key>
$ curl -X POST -H "Authorization: Bearer <api_key>" -d '<data>' /updt
$ curl -X GET /<hash>
Note: Replace `<api_key>`, `<url>`, `<type>`, `<data>`, and `<hash_>` with actual values.
Authentication and Permissions
-------------------------------
The API endpoints require valid API keys for authentication. The API key can be obtained from the pool configuration.
API keys have different permissions:
- Public API Key: Can be used to access direct mirror links and resolve short links.
- Private API Key: Can be used to access read-only endpoints and create new short links.
- Update API Key: Can be used to update the mirror list data.
Please refer to the `pool configuration <https://bypass.censorship.guide/>`_ documentation for more information on managing resource pool API keys.
Response Format
---------------
The API endpoints generally return JSON responses. Successful responses contain the requested data, while failure responses provide relevant error messages.
Error Handling
--------------
In case of errors, the API endpoints return appropriate HTTP status codes and error messages. Clients should handle these errors gracefully and take appropriate actions.