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: []