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:

14
docs/index.rst
View file

@ -6,7 +6,13 @@ Documentation Home
.. toctree::
:maxdepth: 2
:caption: User Guide:
:caption: Publisher Guide
publisher/api.rst
.. toctree::
:maxdepth: 2
:caption: User Guide
user/index.rst
user/proxies.rst
@ -17,17 +23,17 @@ Documentation Home
.. toctree::
:maxdepth: 2
:caption: Admin Guide:
:caption: Admin Guide
admin/install.rst
admin/conf.rst
admin/external.rst
admin/eotk.rst
admin/redirector/index.rst
admin/api/index.rst
.. toctree::
:maxdepth: 2
:caption: Technical Documentation:
:caption: Technical Documentation
tech/index.rst
tech/conf.rst

85
docs/admin/redirector/http.rst → docs/publisher/api.rst
View file

@ -1,11 +1,19 @@
============
HTTP API
Bypass Censorship 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:
The Bypass Censorship API allows publishers to interact with the Bypass Censorship platform and to obtain short links,
snapshot links, and mirror links for their content.
.. note::
This documentation is generic and applies to any deployment of the Bypass Censorship platform.
For the base URL and authentication details specific to your use, contact your vendor.
The API supports the following endpoints:
.. list-table::
:header-rows: 1
@ -19,12 +27,9 @@ The HTTP API allows clients to interact with the application and perform various
* - /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.
- Redirect to the live mirror associated with the given hash.
Authentication
--------------
@ -33,13 +38,12 @@ The API endpoints are protected by authentication. The authentication method dep
- /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.
@ -58,52 +62,41 @@ Response:
/link
^^^^^
Generate a short link or a direct mirror link.
Generate a circumvention link for a specific resource.
This may create a new link or return an already existing link if it has been previously created.
- 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.
- `url` (required): The URL for which a circumvention link needs to be generated.
- `type` (optional): The type of link to generate. Valid values are "live", "short", or "snapshot". 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.
- `expiry` (optional): The duration that a snapshot 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 snapshot.
- `footer_link` (optional): Defines the footer link to be used when publishing a snapshot.
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.
When `footer_text` is not specified, no footer link will be added to a snapshot.
When `footer_link` is not specified, but footer text is specified, a link will be added to a live mirror of the
snapshotted article.
When `type` is specified as "snapshot" and a private API key is specified, a request will be made to the resource to
check the status code returned. If the status code is not 200 and a snapshot had previously been published then that
snapshot will be deleted and future attempts to access it will fail. This mechanism may be used by publishers to
perform self-service take downs of unwanted snapshots.
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.
- Failure: Returns a 403 response if the resource is not on a supported domain.
- Failure: Returns a 404 response if no live mirror exists for the resource.
- Failure: Returns a 500 response if it was not possible to generate a snapshot for a resource.
/<hash>
^^^^^^^
Redirect to the original URL associated with the given hash.
Redirect to the live mirror associated with the given hash.
- Method: GET
- URL: /<hash>
@ -129,10 +122,9 @@ Example Usage
$ 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.
Note: Replace `<api_key>`, `<url>`, `<type>`, and `<hash_>` with actual values.
Authentication and Permissions
-------------------------------
@ -141,18 +133,17 @@ The API endpoints require valid API keys for authentication. The API key can be
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.
- Public API Key: Can be used to access live mirror links, snapshots, and resolve short links.
- Private API Key: Can be used to access live mirror links, snapshots, and create new short links.
Response Format
---------------
The API endpoints generally return JSON responses. Successful responses contain the requested data, while failure responses provide relevant error messages.
The API endpoints 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.
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.