docs: refactor redirector docs into api docs

docs/admin/api/index.rst

@@ -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

docs/admin/redirector/cli.rst

@@ -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`.

docs/admin/redirector/dev.rst

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

docs/index.rst

@@ -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

docs/publisher/api.rst

@@ -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.
+- `url` (required): The URL for which a circumvention 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.
+- `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.
+- `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 GetSiteCopy article.
+- `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 GetSiteCopy article.
+- `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.
+- 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.
-/updt
+- Failure: Returns a 500 response if it was not possible to generate a snapshot for a resource.
-^^^^^
-
-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.
+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.
+- Public API Key: Can be used to access live mirror links, snapshots, and resolve short links.
-- Private API Key: Can be used to access read-only endpoints and create new short links.
+- Private API Key: Can be used to access live mirror links, snapshots, 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.
+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.