diff --git a/api/client-server/report_content.yaml b/api/client-server/report_content.yaml new file mode 100644 index 000000000..f702151d3 --- /dev/null +++ b/api/client-server/report_content.yaml @@ -0,0 +1,78 @@ +# Copyright 2018 Travis Ralston +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Report Content API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/report/{eventId}": + post: + summary: Reports an event as inappropriate. + description: |- + Reports an event as inappropriate to the server, which may then notify + the appropriate people. + operationId: reportContent + parameters: + - in: path + type: string + name: roomId + description: The room in which the event being reported is located. + required: true + x-example: "!637q39766251:example.com" + - in: path + type: string + name: eventId + description: The event to report. + required: true + x-example: "$something:domain.com" + - in: body + name: body + schema: + type: object + example: { + "score": -100, + "reason": "this makes me sad" + } + required: ['score', 'reason'] + properties: + score: + type: integer + description: |- + The score to rate this content as where -100 is most offensive + and 0 is inoffensive. + reason: + type: string + description: The reason the content is being reported. May be blank. + security: + - accessToken: [] + responses: + 200: + description: The event has been reported successfully. + schema: + type: object + examples: + application/json: {} + tags: + - Reporting content diff --git a/changelogs/client_server.rst b/changelogs/client_server.rst index 9833662e5..144bd1e8d 100644 --- a/changelogs/client_server.rst +++ b/changelogs/client_server.rst @@ -48,6 +48,8 @@ Unreleased changes (`#1142 `_). - Add the ``/register/available`` endpoint for username availability (`#1151 `_). + - Add report content API + (`#1264 `_). - Document ``/logout/all`` endpoint (`#1263 `_). diff --git a/specification/modules/report_content.rst b/specification/modules/report_content.rst new file mode 100644 index 000000000..5eca69cd7 --- /dev/null +++ b/specification/modules/report_content.rst @@ -0,0 +1,35 @@ +.. Copyright 2018 Travis Ralston +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Reporting Content +================= + +.. _module:report_content: + +Users may encounter content which they find inappropriate and should be able +to report it to the server administrators or room moderators for review. This +module defines a way for users to report content. + +Content is reported based upon a negative score, where -100 is "most offensive" +and 0 is "inoffensive". + +Client behaviour +---------------- +{{report_content_cs_http_api}} + +Server behaviour +---------------- +Servers are free to handle the reported content however they desire. This may +be a dedicated room to alert server administrators to the reported content or +some other mechanism for notifying the appropriate people. diff --git a/specification/targets.yaml b/specification/targets.yaml index 8ca5ce303..bc9d94c8f 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -67,6 +67,7 @@ groups: # reusable blobs of files when prefixed with 'group:' - modules/dm.rst - modules/ignore_users.rst - modules/stickers.rst + - modules/report_content.rst title_styles: ["=", "-", "~", "+", "^", "`", "@", ":"]