Merge pull request #132 from matrix-org/markjh/room_tags
Document a v2 api for setting tags on roomspull/977/head
Mark Haines
9 years ago
commit
c5f457cee9
@ -0,0 +1,147 @@
|
|||||||
|
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:
|
||||||
|
title: Tags
|
||||||
|
type: object
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"tags": {
|
||||||
|
"work": {"order": "1"},
|
||||||
|
"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: |-
|
||||||
|
Extra data for the tag, e.g. ordering.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: |-
|
||||||
|
{"order": "1"}
|
||||||
|
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": {"order": 1}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@ -0,0 +1,25 @@
|
|||||||
|
{
|
||||||
|
"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": "object",
|
||||||
|
"description": "The tags on the room and their contents.",
|
||||||
|
"additionalProperties": {
|
||||||
|
"title": "Tag",
|
||||||
|
"type": "object"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["type", "content"]
|
||||||
|
}
|
||||||
@ -0,0 +1,48 @@
|
|||||||
|
Room Tagging
|
||||||
|
============
|
||||||
|
|
||||||
|
.. _module:tagging:
|
||||||
|
|
||||||
|
Users can add tags to rooms. Tags are short strings used to label rooms, e.g.
|
||||||
|
"work", "family". 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 received as single ``m.tag`` event in the
|
||||||
|
``account_data`` section of a room in a v2 /sync.
|
||||||
|
|
||||||
|
The ``m.tag`` can also be received in a v1 /events response or in the
|
||||||
|
``account_data`` section of a room in v1 /initialSync. ``m.tag``
|
||||||
|
events appearing in v1 /events will have a ``room_id`` with the room
|
||||||
|
the tags are for.
|
||||||
|
|
||||||
|
Each tag has an associated JSON object with information about the tag, e.g how
|
||||||
|
to order the rooms with a given tag.
|
||||||
|
|
||||||
|
Ordering information is given under the ``order`` key as a string. The string
|
||||||
|
are compared lexicographically by unicode codepoint to determine which should
|
||||||
|
displayed first. So a room with a tag with an ``order`` key of ``"apples"``
|
||||||
|
would appear before a room with a tag with an ``order`` key of ``"oranges"``.
|
||||||
|
If a room has a tag without an ``order`` key then it should appear after the
|
||||||
|
rooms with that tag that have an ``order`` key.
|
||||||
|
|
||||||
|
The name of a tag MUST not exceed 255 bytes.
|
||||||
|
|
||||||
|
The name of a tag should be human readable. When displaying tags for a room a
|
||||||
|
client should display this human readable name. When adding a tag for a room
|
||||||
|
a client may offer a list to choose from that includes all the tags that the
|
||||||
|
user has previously set on any of their rooms.
|
||||||
|
|
||||||
|
Two special names are listed in the specification:
|
||||||
|
|
||||||
|
* ``m.favourite``
|
||||||
|
* ``m.lowpriority``
|
||||||
|
|
||||||
|
{{m_tag_event}}
|
||||||
|
|
||||||
|
Client Behaviour
|
||||||
|
----------------
|
||||||
|
|
||||||
|
{{v2_tags_http_api}}
|
||||||
Loading…
Reference in New Issue