============
HTTP 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:

.. 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.
   * - /updt
     - POST
     - Update the application's data.
   * - /<hash>
     - GET
     - Redirect to the original URL 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.
- /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.

- 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 short link or a direct mirror link.

- 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" or "short". If not provided, "direct" is used.
- `key` (optional): The API key of the pool. If not provided, the public API key is used.

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.

/<hash>
^^^^^^^

Redirect to the original URL 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 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.

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

Response Format
---------------

The API endpoints generally 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.
