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:

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

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