116 lines
3.9 KiB
YAML
116 lines
3.9 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Bypass Censorship Reflector
|
|
description: |
|
|
**The public API for the Bypass Censorship Reflector.**
|
|
|
|
This API is intended to be consumed by tools used for the distribution of mirror links for specific articles.
|
|
These tools may be browser extensions, desktop tools, dedicated web applications, or integrated into CMSs.
|
|
|
|
For any given URL, if a mirror is available, up to 3 kinds of link may be generated.
|
|
To generate a short link requires authentication with an API key, but both direct and onion links may be generated
|
|
without authentication.
|
|
|
|
Link Types
|
|
----------
|
|
|
|
<dl>
|
|
<dt>Short Links (`short`)<dt>
|
|
<dd>
|
|
These are the most convenient for sharing due to their length, and fully support display of OpenGraph
|
|
tags in social media clients.
|
|
</dd>
|
|
<dt>Direct Links (`direct`)</dt>
|
|
<dd>
|
|
These are direct links to the mirror site, and fully support display of OpenGraph tags in social media clients.
|
|
They are less convenient to share due to increased length, however these are available for non-authenticated
|
|
users unlike the short links.
|
|
</dd>
|
|
<dt>Onion Links (`onion`)</dt>
|
|
<dd>
|
|
Where an Onion service has been deployed for a given website, this will return a link to the article on that
|
|
Onion service.
|
|
Visiting Onion services requires that users have downloaded, installed and configured a Tor-aware browser
|
|
such as Tor Browser or Onion Browser.
|
|
</dd>
|
|
</dl>
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
For all endpoints, authentication is performed using an API key.
|
|
This is passed as a query parameter named "key".
|
|
The [/me](#/default/get_me) endpoint can be used to verify an API key without fetching a link.
|
|
|
|
version: 0.0.1
|
|
|
|
servers:
|
|
- url: 'https'
|
|
paths:
|
|
/link:
|
|
get:
|
|
summary: Get a link to a mirror for the given URL.
|
|
description: |
|
|
If an API key is used, the mirror link will use a mirror for the related pool.
|
|
parameters:
|
|
- name: url
|
|
in: query
|
|
description: The URL to generate the link for.
|
|
schema:
|
|
type: string
|
|
example: https://www.sr2.uk/blog/2022/dynamic-bridges/
|
|
- name: type
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: ['direct', 'short', 'onion']
|
|
description: |
|
|
The type of link to generate.
|
|
When no API key is used, the default option is to generate a direct link.
|
|
When an API key is used, the default option is to generate a short link.
|
|
responses:
|
|
200:
|
|
description: The URL for the mirror.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
url:
|
|
type: string
|
|
example: "https://fake.cloudfront.net/blog/2022/dynamic-bridges/"
|
|
403:
|
|
description: The given API key was invalid.
|
|
404:
|
|
description: No link could be generated from the given parameters.
|
|
502:
|
|
description: The application is down for maintenance.
|
|
/me:
|
|
get:
|
|
summary: Get information about the authenticated user.
|
|
responses:
|
|
200:
|
|
description: Information about the authenticated user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
description:
|
|
type: string
|
|
example: "Link Distribution Team A"
|
|
403:
|
|
description: The given API key was invalid.
|
|
502:
|
|
description: The application is down for maintenance.
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: query
|
|
name: key
|
|
description: API key provisioned in the Bypass Censorship Portal for the relevant resource pool.
|
|
|
|
security:
|
|
- ApiKeyAuth: []
|