docs: some reorganisation of documentation

schemas/publisher.yaml

@@ -0,0 +1,132 @@
+openapi: 3.0.3
+info:
+  title: Bypass Censorship API
+  description: |
+    The Bypass Censorship API allows publishers to interact with the Bypass Censorship platform and to obtain short links,
+    snapshot links, and mirror links for their content.
+    
+    **Note**: This documentation is generic and applies to any deployment of the Bypass Censorship platform.
+    For the base URL and authentication details specific to your use, contact your vendor.
+  version: 1.0.0
+servers:
+  - url: https://example.com
+    description: Example server
+paths:
+  /me:
+    get:
+      summary: Retrieve information about the authenticated user's pool
+      parameters:
+        - name: key
+          in: query
+          description: The API key of the pool. If not provided, the public API key is used.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Information about the user's pool
+        '403':
+          description: Invalid API key
+  /link:
+    get:
+      summary: Generate a circumvention link for a specific resource
+      parameters:
+        - name: url
+          in: query
+          description: The URL for which a circumvention link needs to be generated.
+          required: true
+          schema:
+            type: string
+        - name: type
+          in: query
+          description: |
+            The type of link to generate. Valid values are "live", "short", or "snapshot".
+            If not provided, "direct" is used.
+          required: false
+          schema:
+            type: string
+            enum: [live, short, snapshot, direct]
+        - name: key
+          in: query
+          description: The API key of the pool. If not provided, the public API key is used.
+          required: false
+          schema:
+            type: string
+        - name: expiry
+          in: query
+          description: |
+            The duration that a snapshot will remain published for. Valid values are "long" and "short".
+            If not provided, "short" is used.
+          required: false
+          schema:
+            type: string
+            enum: [long, short]
+        - name: footer_text
+          in: query
+          description: Defines the footer text to be used when publishing a snapshot.
+          required: false
+          schema:
+            type: string
+        - name: footer_link
+          in: query
+          description: Defines the footer link to be used when publishing a snapshot.
+          required: false
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Generated circumvention link
+        '403':
+          description: Resource not on a supported domain
+        '404':
+          description: No live mirror exists for the resource
+        '500':
+          description: Could not generate a snapshot for the resource
+  /{hash}:
+    get:
+      summary: Redirect to the live mirror associated with the given hash
+      parameters:
+        - name: hash
+          in: path
+          description: The hash associated with the short link
+          required: true
+          schema:
+            type: string
+        - name: force
+          in: query
+          description: Always redirect to a mirror and ignore GeoIP information.
+          required: false
+          schema:
+            type: boolean
+        - name: force_ip
+          in: query
+          description: Override the client IP address and base the GeoIP lookup on this IP address instead.
+          required: false
+          schema:
+            type: string
+      responses:
+        '302':
+          description: Redirects the client to the original URL
+          headers:
+            Location:
+              description: The URL of the live mirror
+              schema:
+                type: string
+        '404':
+          description: The hash is invalid or not found
+components:
+  securitySchemes:
+    apiKeyAuth:
+      type: apiKey
+      in: query
+      name: key