wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #178 from matrix-org/daniel/directory

Browse source 
Fix and include /directory api docs
This commit is contained in:
Daniel Wagner-Hall 2015-11-27 16:21:15 +00:00
commit bc514dc9c4
2 changed files with 48 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

48
api/client-server/v1/directory.yaml
View file

@ -29,6 +29,7 @@ paths:
name: roomAlias
description: The room alias to set.
required: true
x-example: "#monkeys:matrix.org"
- in: body
name: roomInfo
description: Information about this room alias.
@ -39,11 +40,18 @@ paths:
room_id:
type: string
description: The room ID to set.
example: |-
{
"room_id": "!abnjk1jdasj98:capuchins.com"
}
responses:
200:
description: The mapping was created.
examples:
application/json: |-
{}
schema:
type: object # empty json object
type: object
get:
summary: Get the room ID corresponding to this room alias.
parameters:
@ -52,6 +60,7 @@ paths:
name: roomAlias
description: The room alias.
required: true
x-example: "#monkeys:matrix.org"
responses:
200:
description: The room ID and other information for this alias.
@ -67,10 +76,38 @@ paths:
items:
type: string
description: A server which is aware of this room ID.
examples:
application/json: |-
{
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
"matrix.org",
"another.com"
]
}
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: |-
{
"errcode": "M_NOT_FOUND",
"error": "Room ID !abnjk1jdasj98:capuchins.com not found."
}
409:
description: A room alias with that name already exists.
examples:
application/json: |-
{
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
delete:
summary: Remove a mapping of room alias to room ID.
description: |-
Remove a mapping of room alias to room ID.
Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
security:
- accessToken: []
parameters:
@ -79,9 +116,12 @@ paths:
name: roomAlias
description: The room alias to remove.
required: true
x-example: "#monkeys:matrix.org"
responses:
200:
description: The mapping was removed.
description: The mapping was deleted.
examples:
application/json: |-
{}
schema:
type: object # empty json object
type: object

24
specification/client_server_api.rst
View file

@ -892,19 +892,9 @@ client has to use the the following API.
Room aliases
~~~~~~~~~~~~
.. NOTE::
This section is a work in progress.
Room aliases can be created by sending a ``PUT /directory/room/<room alias>``::
{
"room_id": <room id>
}
They can be deleted by sending a ``DELETE /directory/room/<room alias>`` with
no content. Only some privileged users may be able to delete room aliases, e.g.
server admins, the creator of the room alias, etc. This specification does not
outline the privilege level required for deleting room aliases.
Servers may host aliases for rooms with human-friendly names. Aliases take the
form ``#friendlyname:server.name``.
As room aliases are scoped to a particular home server domain name, it is
likely that a home server will reject attempts to maintain aliases on other
@ -921,17 +911,11 @@ appears to have a room alias of ``#alias:example.com``, this SHOULD be checked
to make sure that the room's ID matches the ``room_id`` returned from the
request.
Room aliases can be checked in the same way they are resolved; by sending a
``GET /directory/room/<room alias>``::
{
"room_id": <room id>,
"servers": [ <domain>, <domain2>, <domain3> ]
}
Home servers can respond to resolve requests for aliases on other domains than
their own by using the federation API to ask other domain name home servers.
{{directory_http_api}}
Permissions
~~~~~~~~~~~