From b53d2580ee814b93465c8dd0683a2c63adf10936 Mon Sep 17 00:00:00 2001 From: Iain Learmonth Date: Fri, 28 Oct 2022 14:54:50 +0100 Subject: [PATCH] reflector: update with some introductory prose --- schemas/reflector.yaml | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/schemas/reflector.yaml b/schemas/reflector.yaml index 4d3affa..e945097 100644 --- a/schemas/reflector.yaml +++ b/schemas/reflector.yaml @@ -1,7 +1,47 @@ openapi: 3.0.3 info: title: Bypass Censorship Reflector - description: The public API for the 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 + ---------- + +
+
Short Links (`short`)
+
+ These are the most convenient for sharing due to their length, and fully support display of OpenGraph + tags in social media clients. +
+
Direct Links (`direct`)
+
+ 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. +
+
Onion Links (`onion`)
+
+ 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. +
+
+ + 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: