diff --git a/docs/admin/redirector/config.rst b/docs/admin/api/config.rst similarity index 100% rename from docs/admin/redirector/config.rst rename to docs/admin/api/config.rst diff --git a/docs/admin/redirector/index.rst b/docs/admin/api/index.rst similarity index 90% rename from docs/admin/redirector/index.rst rename to docs/admin/api/index.rst index 87ddf34..d5bba10 100644 --- a/docs/admin/redirector/index.rst +++ b/docs/admin/api/index.rst @@ -32,8 +32,6 @@ This documentation is structured into the following sections: 1. :doc:`Installation `: Provides instructions for installing and setting up the Short Link Redirector application. 2. :doc:`Configuration `: Explains the configuration options and how to customize the application's behavior. -3. :doc:`HTTP API Reference `: Details the available HTTP API endpoints and their usage. -4. :doc:`Command-Line Interface (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 diff --git a/docs/admin/redirector/install.rst b/docs/admin/api/install.rst similarity index 100% rename from docs/admin/redirector/install.rst rename to docs/admin/api/install.rst diff --git a/docs/admin/redirector/cli.rst b/docs/admin/redirector/cli.rst deleted file mode 100644 index 0ac1e94..0000000 --- a/docs/admin/redirector/cli.rst +++ /dev/null @@ -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 - -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 - -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 - -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 - -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 ` 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`. diff --git a/docs/admin/redirector/dev.rst b/docs/admin/redirector/dev.rst deleted file mode 100644 index a489ef5..0000000 --- a/docs/admin/redirector/dev.rst +++ /dev/null @@ -1,7 +0,0 @@ -=================== -Developer Reference -=================== - -.. automodule:: app - :members: - diff --git a/docs/index.rst b/docs/index.rst index f4527b0..d7509a9 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/admin/redirector/http.rst b/docs/publisher/api.rst similarity index 51% rename from docs/admin/redirector/http.rst rename to docs/publisher/api.rst index 8dde8ae..c6ed375 100644 --- a/docs/admin/redirector/http.rst +++ b/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. * - / - 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. / ^^^^^^^ -Redirect to the original URL associated with the given hash. +Redirect to the live mirror associated with the given hash. - Method: GET - URL: / @@ -129,10 +122,9 @@ Example Usage $ curl -X GET /me?key= $ curl -X GET /link?url=&type=&key= - $ curl -X POST -H "Authorization: Bearer " -d '' /updt $ curl -X GET / -Note: Replace ``, ``, ``, ``, and `` with actual values. +Note: Replace ``, ``, ``, and `` 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 `_ 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.