Add protocol draft

PROTOCOL.md

@@ -0,0 +1,122 @@
+# Session Listing Provider protocol
+
+## Mission statement
+
+A listing provider should inform the user of existing Community Servers, organized in one or more listings and supplemented with information provided by the maintainer.
+
+A listing provider should also include an endpoint to retrieve all listings currently available.
+
+A listing provider should be available via Session's onion request to provide anonymity to users while requesting listings.
+
+## Approaches to extending the SOGS API
+
+Given that the listing provider API may be ahead in development of the SOGS API and conflicts between data keys can arise, there are several approaches to consider. To ensure consistency, the chosen approach should be considered binding to all endpoints of the protocol including information fetched from mixed sources.
+
+```json5
+// Note: Key names subject to change.
+
+// Side-by-side (Potentially collision-prone):
+
+{
+    "name": "Community Name",
+    "description": "Lorem ipsum dolor sit amet",
+    "tags": ["maintainer-tag"],
+    "nsfw": false
+}
+
+// Wrap SOGS API-provided info:
+
+{
+    "api": {
+        "name": "Community Name",
+        "description": "Lorem ipsum dolor sit amet",
+    },
+    "tags": ["maintainer-tag"],
+    "nsfw": false
+}
+
+// Wrap maintainer-provided info:
+
+{
+    "name": "Community Name",
+    "description": "Lorem ipsum dolor sit amet",
+    "extras": {
+        "tags": ["maintainer-tag"],
+        "nsfw": false
+    }
+}
+
+// Wrap both:
+
+{
+    "api": {
+        "name": "Community Name",
+        "description": "Lorem ipsum dolor sit amet"
+    },
+    "extras": {
+        "tags": ["maintainer-tag"],
+        "nsfw": false
+    }
+}
+
+```
+
+## Maintainer-provided info
+
+In addition to information obtained from the SOGS API, the listing provider must include the following information:
+
+- Join URL of Community and/or information needed to reconstruct it.
+  - Reason: User must be able to connect to the Community server securely.
+- For each listing:
+  - Listing identifier.
+  - Human-readable name.
+
+The listing provider may include the following information:
+
+- For each listing:
+  - Date of creation.
+  - Date of last update.
+- For Communities or Community listings:
+  - Age rating and/or observed degree of compliance with Session Terms of Service.
+  - Date maintainer has last verified age rating and/or observed ToS compliance.
+  - Date of inclusion in listing provider.
+- For Communities:
+  - Language(s) spoken in the Community.
+  - Metric(s) of recent message frequency.
+  - Additional description.
+  - User-provided and/or maintainer-provided tags.
+  - SOGS-provided server-wide name and icon.
+
+## Draft of endpoint specifications
+
+### POST `/oxen/v4/lsrpc`
+
+Description: Parse a Session onion request and proceed with the corresponding endpoint.
+
+Error responses:
+
+- TBD
+
+See <https://github.com/oxen-io/session-pysogs/blob/dev/sogs/routes/onion_request.py#L269>.
+
+### GET `/listings`
+
+Description: Enumerate the identifiers of the listings hosted by the listing provider.
+
+Example response:
+
+```json
+{
+    listings: ["tech", "languages", "privsec", "casual", "nsfw", "all"]
+}
+```
+
+### GET `/listing/<listingId>`
+
+Description: Show information about the listing with the given ID.
+
+Error responses:
+
+- `404 Not Found`
+  - Returned if the given listing does not exist.
+  

README.md

@@ -81,7 +81,7 @@ Below follow some alternate solutions to provide Community discoverability that,
 
 ## Listing provider model: The What
 
-One can imagine a simple REST API to retrieve a list of communities from a listing provider; all Session would have to do is include the following UI below the community list:
+One can imagine a [simple REST API](PROTOCOL.md) to retrieve a list of communities from a listing provider; all Session would have to do is include the following UI below the community list:
 
 ```txt
 Add more communities from list: