Common Community Client API

➤Source (manually imported from Hedgedoc)

This is a brief draft of what a common, standards-based client-server API for community chat-like apps could look like. The intent is to allow a variety of clients and a variety of servers, all with different intents, separately implementing a common-denominator API for client apps to use.

Authentication

Clients MUST be authenticated to use all non-GET endpoints, and any GET endpoints marked for authentication. This is handled by the server, but clients should expect to use OAuth2 against the server to ask for chat rights.

Well-Known Endpoints

GET [11m/.well-known/cccapi-host.json[0m

Should respond with a static file, modeled after the following:

json
{
    "base_url": "https://example.com/_community_clients_/",
    "display_name": "Example Community",
    "authorize": "https://example.com/oauth2/authorize"
}

[11mbase_url[0m: The URL to use as the prefix for all of the endpoints below. [1mRequired.[0m
[11mdisplay_name[0m: The name to display in apps for the community. [1mOptional,[0m and defaults to the domain name.
[11mauthorize[0m: The endpoint clients should open a browser to. [1mRequired.[0m

Endpoints

GET [11m/topics[0m

Authorization SHOULD be required, but it might not be depending on the sensitivity.
May return HTTP status code [11m404[0m if the server does not support topics.

Lists public topics, or topics that the authenticated user has access to. Topics are roughly equivalent to channels.

This does NOT correspond with the topics a user is listening to. This should be remembered in the client.

Response example ([11mapplication/json[0m):

json
{
    "topicId": {
        "name": "Topic name",
        "description": "The topic description to show in a list."
    },
    "topicId2": {
        "name": "Topic 2 title",
        "description": "Topic 2 tagline or summary"
    },
    "emptyTopic": {}
}

Response example ([11mtext/csv[0m):

csv
topicId,Topic name,Topic description
topicId2,Topic 2 name,Topic 2 description
emptyTopic,,

GET [11m/topic/:id/messages[0m

Authorization required if a topic is not public.

Lists the messages in a room.

Response example ([11mmultipart/mixed[0m):

http
200 OK
Content-Type: multipart/mixed; boundary="-Boundary-c29dab8"
X-Earliest-Message-ID: <EarliestMessageID>
X-Latest-Message-ID: <LatestMessageID>

---Boundary-c29dab8
Content-Type: text/markdown; variant=CommonMark
From: Display Name <somekindofid@example.com>
From-Avatar-URL: https://example.com/avatar.png
Date: Wed, 24 May 2023 18:13:33 +0000
Message-ID: <EarliestMessageID>

This is the earliest message.
---Boundary-c29dab8
Content-Type: text/markdown; variant=GFM
From: Display Name <somekindofid@example.com>
Date: Wed, 24 May 2023 18:14:18 +0000
Message-ID: <MessageID2>

I could write a table here but I won't.
---Boundary-c29dab8
Content-Type: text/plain
From: Display Name <somekindofid@example.com>
Date: Wed, 24 May 2023 18:15:23 +0000
Message-ID: <LatestMessageID>

This is the last message. It's plain text.
---Boundary-c29dab8--