149 lines
4.9 KiB
ReStructuredText
149 lines
4.9 KiB
ReStructuredText
=====================
|
|
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.
|