💾 Archived View for blakes.dev › hdoc › 4A6xCFoqTxK_D4VkQKntvA.md captured on 2024-05-10 at 10:55:31.

View Raw

More Information

-=-=-=-=-=-=-

# Common Community Client API
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 `/.well-known/cccapi-host.json`
Should respond with a static file, modeled after the following:

{

"base_url": "https://example.com/_community_clients_/",

"display_name": "Example Community",

"authorize": "https://example.com/oauth2/authorize"

}

	
`base_url`: The URL to use as the prefix for all of the endpoints below. **Required.**
	
`display_name`: The name to display in apps for the community. **Optional,** and defaults to the domain name.
	
`authorize`: The endpoint clients should open a browser to. **Required.**


## Endpoints
### GET `/topics`

	
Authorization SHOULD be required, but it might not be depending on the sensitivity.
	
May return HTTP status code `404` 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 (`application/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 (`text/csv`):

topicId,Topic name,Topic description

topicId2,Topic 2 name,Topic 2 description

emptyTopic,,

### GET `/topic/:id/messages`

	
Authorization required if a topic is not public.


Lists the messages in a room.

Response example (`multipart/mixed`):

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--

Response example (`application/json`):

{

"latest": "LatestMessageID",

"earliest": "EarliestMessageID",

"messages": [

{

"type": "text/markdown; variant=CommonMark",

"from": {

"name": "Display Name",

"id": "somekindofid@example.com"

},

"timestamp": 1684966413000,

"content": "This is the earliest message.",

},

{

"type": "text/markdown; variant=GFM",

"from": {

"name": "Display Name",

"id": "somekindofid@example.com"

},

"timestamp": 1684966458000,

"content": "I could write a table here but I won't."

},

{

"type": "text/plain",

"from": {

"name": "Display Name",

"id": "somekindofid@example.com"

},

"timestamp": 1684966523000,

"content": "This is the last message. It's plain text."

}

]

}