Document a v2 api for setting tags on rooms
parent
696f75d80b
commit
12e33a3b09
@ -0,0 +1,148 @@
|
||||
swagger: '2.0'
|
||||
info:
|
||||
title: "Matrix Client-Server tag API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/v2_alpha
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
accessToken:
|
||||
type: apiKey
|
||||
description: The user_id or application service access_token
|
||||
name: access_token
|
||||
in: query
|
||||
paths:
|
||||
"/user/{userId}/rooms/{roomId}/tags":
|
||||
get:
|
||||
summary: List the tags for a room.
|
||||
description: |-
|
||||
List the tags set by a user on a room.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the user to get tags for. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the room to get tags for.
|
||||
x-example: "!726s6s6q:example.com"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The list of tags for the user for the room.
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
tags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
examples:
|
||||
application/json: |-
|
||||
{
|
||||
"tags": [
|
||||
"work",
|
||||
"pinned"
|
||||
]
|
||||
}
|
||||
"/user/{userId}/rooms/{roomId}/tags/{tag}":
|
||||
put:
|
||||
summary: Add a tag to a room.
|
||||
description: |-
|
||||
Add a tag to the room.
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the user to add a tag for. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the room to add a tag to.
|
||||
x-example: "!726s6s6q:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: tag
|
||||
required: true
|
||||
description: |-
|
||||
The tag to add.
|
||||
x-example: "work"
|
||||
- in: body
|
||||
name: body
|
||||
required: true
|
||||
description: |-
|
||||
An empty JSON object.
|
||||
schema:
|
||||
type: object
|
||||
example: |-
|
||||
{}
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The tag was successfully added.
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
||||
delete:
|
||||
summary: Remove a tag from the room.
|
||||
description: |-
|
||||
Remove a tag from the room.
|
||||
security:
|
||||
- access_token: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: userId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the user to remove a tag for. The access token must be
|
||||
authorized to make requests for this user id.
|
||||
x-example: "@alice:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
required: true
|
||||
description: |-
|
||||
The id of the room to remove a tag from.
|
||||
x-example: "!726s6s6q:example.com"
|
||||
- in: path
|
||||
type: string
|
||||
name: tag
|
||||
required: true
|
||||
description: |-
|
||||
The tag to remove.
|
||||
x-example: "work"
|
||||
responses:
|
||||
200:
|
||||
description:
|
||||
The tag was successfully removed
|
||||
schema:
|
||||
type: object
|
||||
examples:
|
||||
application/json: |-
|
||||
{}
|
@ -0,0 +1,8 @@
|
||||
{
|
||||
"type": "m.tag",
|
||||
"content": {
|
||||
"tags": [
|
||||
"work"
|
||||
]
|
||||
}
|
||||
}
|
@ -0,0 +1,23 @@
|
||||
{
|
||||
"type": "object",
|
||||
"title": "Tag Event",
|
||||
"description": "Informs the client of tags on a room.",
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["m.tag"]
|
||||
},
|
||||
"content": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"tags": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["type", "content"]
|
||||
}
|
@ -0,0 +1,21 @@
|
||||
Room Tagging
|
||||
============
|
||||
|
||||
.. _module:tagging:
|
||||
|
||||
Users can add tags to rooms. Tags are short strings used to label rooms, e.g.
|
||||
"work", "familly". A room may have multiple tags. Tags are only visible to the
|
||||
user that set them but are shared across all their devices.
|
||||
|
||||
Events
|
||||
------
|
||||
|
||||
The tags on a room are passed as single ``m.tag`` event in the ``ephemeral``
|
||||
section of a v2 room sync.
|
||||
|
||||
{{m_tag_event}}
|
||||
|
||||
Client Behaviour
|
||||
----------------
|
||||
|
||||
{{v2_tags_http_api}}
|
Loading…
Reference in New Issue