docs: refactor redirector docs into api docs

2024-11-09 11:11:11 +00:00 · 2024-11-09 11:11:11 +00:00 · c795a70d80
commit c795a70d80
parent 73439a8121
7 changed files with 48 additions and 158 deletions
--- a/docs/publisher/api.rst
+++ b/docs/publisher/api.rst
@ -0,0 +1,149 @@
+============
+Bypass Censorship API
+============
+
+Introduction
+------------
+
+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
+
+   * - Endpoint
+     - Method
+     - Description
+   * - /me
+     - GET
+     - Retrieve information about the authenticated user's pool.
+   * - /link
+     - GET
+     - Generate a short link or a direct mirror link.
+   * - /<hash>
+     - GET
+     - Redirect to the live mirror 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.
+
+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 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 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 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 `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 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 live mirror 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 GET /<hash>
+
+Note: Replace `<api_key>`, `<url>`, `<type>`, 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 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 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.