OpenAPI docs
This commit is contained in:
Denis Arh
@@ -1,4 +1,4 @@
|
||||
.PHONY: pack build help qa critic vet codegen provision
|
||||
.PHONY: pack build help qa critic vet codegen provision docs
|
||||
|
||||
GO = go
|
||||
GOGET = $(GO) get -u
|
||||
@@ -159,6 +159,9 @@ clean.codegen:
|
||||
provision:
|
||||
$(MAKE) --directory=provision clean all
|
||||
|
||||
docs: $(STATIK)
|
||||
$(STATIK) -p docs -m -Z -f -src=./docs
|
||||
|
||||
|
||||
#######################################################################################################################
|
||||
# Quality Assurance
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
# Corteza API documentation
|
||||
|
||||
WARNING: Work in progress
|
||||
|
||||
This is the first step in migration towards full OpenAPI standards support.`
|
||||
|
||||
## Original/starting state (pre `2020.9`; deprecated):
|
||||
Home-brew API definition format in JSON, still available under `api/*/spec.json`.
|
||||
This is still needed for controller/request/handler codegens. Documentation generators are disabled.
|
||||
|
||||
## Current state (`2020.9`)
|
||||
In branch `2020.12.x` we're experimenting with first step toward conversion to OpenAPI 3.0 YAML files for API
|
||||
definition. There is a converter available in https://github.com/cortezaproject/openapi3-converter[cortezaproject/openapi3-converter]
|
||||
that takes those custom YAML files and converts them to OpenAPI format.
|
||||
|
||||
## Goal (target `2020.12`)
|
||||
Generate HTTP handlers and all auxilary code and documentation from YAML files in OpenAPI 3.0 format
|
||||
+1931
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,63 @@
|
||||
<!-- HTML for static distribution bundle build -->
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Corteza Server REST API Documentation</title>
|
||||
<link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@3/swagger-ui.css" >
|
||||
<link rel="icon" type="image/png" href="https://unpkg.com/swagger-ui-dist@3/favicon-32x32.png" sizes="32x32" />
|
||||
<link rel="icon" type="image/png" href="https://unpkg.com/swagger-ui-dist@3/favicon-16x16.png" sizes="16x16" />
|
||||
<style>
|
||||
html
|
||||
{
|
||||
box-sizing: border-box;
|
||||
overflow: -moz-scrollbars-vertical;
|
||||
overflow-y: scroll;
|
||||
}
|
||||
|
||||
*,
|
||||
*:before,
|
||||
*:after
|
||||
{
|
||||
box-sizing: inherit;
|
||||
}
|
||||
|
||||
body
|
||||
{
|
||||
margin:0;
|
||||
background: #fafafa;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div id="swagger-ui"></div>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js" charset="UTF-8"></script>
|
||||
<script src="https://unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
|
||||
|
||||
<script>
|
||||
window.onload = function() {
|
||||
// https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/
|
||||
window.ui = SwaggerUIBundle({
|
||||
urls: [
|
||||
{ url: "/docs/system.yaml", name: 'System' },
|
||||
{ url: "/docs/compose.yaml", name: 'Compose' },
|
||||
{ url: "/docs/messaging.yaml", name: 'Messaging' },
|
||||
],
|
||||
dom_id: '#swagger-ui',
|
||||
deepLinking: true,
|
||||
presets: [
|
||||
SwaggerUIBundle.presets.apis,
|
||||
SwaggerUIStandalonePreset
|
||||
],
|
||||
plugins: [
|
||||
SwaggerUIBundle.plugins.DownloadUrl
|
||||
],
|
||||
layout: "StandaloneLayout",
|
||||
|
||||
supportedSubmitMethods: [],
|
||||
})
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,932 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: Corteza messaging API
|
||||
description: Corteza messaging REST API definition
|
||||
version: 2020.12
|
||||
contact:
|
||||
email: info@cortezaproject.org
|
||||
license:
|
||||
name: Apache 2.0
|
||||
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
|
||||
paths:
|
||||
/commands/:
|
||||
get:
|
||||
tags:
|
||||
- Commands
|
||||
summary: List of available commands
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
/status/:
|
||||
get:
|
||||
tags:
|
||||
- Status
|
||||
summary: See all current statuses
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
post:
|
||||
tags:
|
||||
- Status
|
||||
summary: Set user's status
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_0
|
||||
icon:
|
||||
type: string
|
||||
description: Status icon
|
||||
message:
|
||||
type: string
|
||||
description: Status message
|
||||
expires:
|
||||
type: string
|
||||
description: >-
|
||||
Clear status when it expires (eg: when-active, afternoon,
|
||||
tomorrow 1h, 30m, 1 PM, 2019-05-20)
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_0
|
||||
delete:
|
||||
tags:
|
||||
- Status
|
||||
summary: Clear status
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
/activity/:
|
||||
post:
|
||||
tags:
|
||||
- User activity
|
||||
summary: >-
|
||||
Sends user's activity to all subscribers; globally or per
|
||||
channel/message.
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_1
|
||||
channelID:
|
||||
type: string
|
||||
description: >-
|
||||
Channel ID, if set, activity will be send only to subscribed
|
||||
users
|
||||
messageID:
|
||||
type: string
|
||||
description: 'Message ID, if set, channelID must be set as well'
|
||||
kind:
|
||||
type: string
|
||||
description: Arbitrary string
|
||||
required:
|
||||
- kind
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_1
|
||||
/channels/:
|
||||
get:
|
||||
tags:
|
||||
- Channels
|
||||
summary: List channels
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: query
|
||||
name: query
|
||||
description: Search query
|
||||
required: false
|
||||
schema: &ref_2
|
||||
type: string
|
||||
post:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Create new channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_3
|
||||
name:
|
||||
type: string
|
||||
description: Name of Channel
|
||||
topic:
|
||||
type: string
|
||||
description: Subject of Channel
|
||||
type:
|
||||
type: string
|
||||
description: Channel type
|
||||
membershipPolicy:
|
||||
type: string
|
||||
description: 'Membership policy (eg: featured, forced)?'
|
||||
members:
|
||||
type: array
|
||||
items: *ref_2
|
||||
description: Initial members of the channel
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_3
|
||||
'/channels/{channelID}':
|
||||
put:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Update channel details
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: &ref_5
|
||||
type: string
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_4
|
||||
name:
|
||||
type: string
|
||||
description: Name of Channel
|
||||
topic:
|
||||
type: string
|
||||
description: Subject of Channel
|
||||
membershipPolicy:
|
||||
type: string
|
||||
description: 'Membership policy (eg: featured, forced)?'
|
||||
type:
|
||||
type: string
|
||||
description: Channel type
|
||||
organisationID:
|
||||
type: string
|
||||
description: Move channel to different organisation
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_4
|
||||
get:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Read channel details
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/state':
|
||||
put:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Update channel state
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_6
|
||||
state:
|
||||
type: string
|
||||
description: 'Valid values: delete, undelete, archive, unarchive'
|
||||
required:
|
||||
- state
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_6
|
||||
'/channels/{channelID}/flag':
|
||||
put:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Update channel membership flag
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_7
|
||||
flag:
|
||||
type: string
|
||||
description: 'Valid values: pinned, hidden, ignored'
|
||||
required:
|
||||
- flag
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_7
|
||||
delete:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Remove channel membership flag
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/members':
|
||||
get:
|
||||
tags:
|
||||
- Channels
|
||||
summary: List channel members
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/members/{userID}':
|
||||
put:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Join channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: userID
|
||||
description: Member ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
delete:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Remove member from channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: userID
|
||||
description: Member ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/invite':
|
||||
post:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Join channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_8
|
||||
userID:
|
||||
type: array
|
||||
items: *ref_2
|
||||
description: User ID
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_8
|
||||
'/channels/{channelID}/attach':
|
||||
post:
|
||||
tags:
|
||||
- Channels
|
||||
summary: Attach file to channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_9
|
||||
replyTo:
|
||||
type: string
|
||||
description: Upload as a reply
|
||||
upload:
|
||||
type: string
|
||||
format: binary
|
||||
description: File to upload
|
||||
required:
|
||||
- upload
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_9
|
||||
'/channels/{channelID}/messages/':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Post new message to the channel
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_10
|
||||
message:
|
||||
type: string
|
||||
description: Message contents (markdown)
|
||||
required:
|
||||
- message
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_10
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/messages/command/{command}/exec':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Execute command
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: command
|
||||
description: Command to be executed
|
||||
required: true
|
||||
schema: *ref_2
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_11
|
||||
input:
|
||||
type: string
|
||||
description: Arbitrary command input
|
||||
params:
|
||||
type: array
|
||||
items: *ref_2
|
||||
description: Command parameters
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_11
|
||||
'/channels/{channelID}/messages/mark-as-read':
|
||||
get:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Manages read/unread messages in a channel or a thread
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: threadID
|
||||
description: 'ID of thread (messageID) '
|
||||
required: false
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: lastReadMessageID
|
||||
description: ID of the last read message
|
||||
required: false
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/messages/{messageID}':
|
||||
put:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Edit existing message
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_12
|
||||
message:
|
||||
type: string
|
||||
description: Message contents (markdown)
|
||||
required:
|
||||
- message
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_12
|
||||
delete:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Delete existing message
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/messages/{messageID}/replies':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Reply to a message
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_13
|
||||
message:
|
||||
type: string
|
||||
description: Message contents (markdown)
|
||||
required:
|
||||
- message
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_13
|
||||
'/channels/{channelID}/messages/{messageID}/pin':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Pin message to channel (public bookmark)
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
delete:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Pin message to channel (public bookmark)
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/messages/{messageID}/bookmark':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Bookmark a message (private bookmark)
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
delete:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Remove boomark from message (private bookmark)
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
'/channels/{channelID}/messages/{messageID}/reaction/{reaction}':
|
||||
post:
|
||||
tags:
|
||||
- Messages
|
||||
summary: React to a message
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: reaction
|
||||
description: Reaction
|
||||
required: true
|
||||
schema: *ref_2
|
||||
delete:
|
||||
tags:
|
||||
- Messages
|
||||
summary: Delete reaction from a message
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: channelID
|
||||
description: Channel ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: messageID
|
||||
description: Message ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: reaction
|
||||
description: Reaction
|
||||
required: true
|
||||
schema: *ref_2
|
||||
'/attachment/{attachmentID}/original/{name}':
|
||||
get:
|
||||
tags:
|
||||
- Attachments
|
||||
summary: Serves attached file
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: attachmentID
|
||||
description: Attachment ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: name
|
||||
description: File name
|
||||
required: true
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: sign
|
||||
description: Signature
|
||||
required: true
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: userID
|
||||
description: User ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: download
|
||||
description: Force file download
|
||||
required: false
|
||||
schema: &ref_14
|
||||
type: boolean
|
||||
'/attachment/{attachmentID}/preview.{ext}':
|
||||
get:
|
||||
tags:
|
||||
- Attachments
|
||||
summary: Serves preview of an attached file
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: attachmentID
|
||||
description: Attachment ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
- in: path
|
||||
name: ext
|
||||
description: Preview extension/format
|
||||
required: true
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: sign
|
||||
description: Signature
|
||||
required: true
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: userID
|
||||
description: User ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
/search/messages:
|
||||
get:
|
||||
tags:
|
||||
- Search entry point
|
||||
summary: Search for messages
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: query
|
||||
name: query
|
||||
description: Search query
|
||||
required: false
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: channelID
|
||||
description: Filter by channels
|
||||
required: false
|
||||
schema:
|
||||
type: array
|
||||
items: *ref_2
|
||||
- in: query
|
||||
name: afterMessageID
|
||||
description: ID of the first message in the list (exclusive)
|
||||
required: false
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: beforeMessageID
|
||||
description: ID of the last message in the list (exclusive)
|
||||
required: false
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: fromMessageID
|
||||
description: ID of the first message in the list (inclusive)
|
||||
required: false
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: toMessageID
|
||||
description: ID of the last message the list (inclusive)
|
||||
required: false
|
||||
schema: *ref_5
|
||||
- in: query
|
||||
name: threadID
|
||||
description: Filter by thread message ID
|
||||
required: false
|
||||
schema:
|
||||
type: array
|
||||
items: *ref_2
|
||||
- in: query
|
||||
name: userID
|
||||
description: Filter by one or more user
|
||||
required: false
|
||||
schema:
|
||||
type: array
|
||||
items: *ref_2
|
||||
- in: query
|
||||
name: type
|
||||
description: 'Filter by message type (text, inlineImage, attachment, ...)'
|
||||
required: false
|
||||
schema:
|
||||
type: array
|
||||
items: *ref_2
|
||||
- in: query
|
||||
name: pinnedOnly
|
||||
description: Return only pinned messages
|
||||
required: false
|
||||
schema: *ref_14
|
||||
- in: query
|
||||
name: bookmarkedOnly
|
||||
description: Only bookmarked messages
|
||||
required: false
|
||||
schema: *ref_14
|
||||
- in: query
|
||||
name: limit
|
||||
description: Max number of messages
|
||||
required: false
|
||||
schema: &ref_15
|
||||
type: string
|
||||
/search/threads:
|
||||
get:
|
||||
tags:
|
||||
- Search entry point
|
||||
summary: Search for threads
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: query
|
||||
name: query
|
||||
description: Search query
|
||||
required: false
|
||||
schema: *ref_2
|
||||
- in: query
|
||||
name: channelID
|
||||
description: Filter by channels
|
||||
required: false
|
||||
schema:
|
||||
type: array
|
||||
items: *ref_2
|
||||
- in: query
|
||||
name: limit
|
||||
description: Max number of messages
|
||||
required: false
|
||||
schema: *ref_15
|
||||
/permissions/:
|
||||
get:
|
||||
tags:
|
||||
- Permissions
|
||||
summary: Retrieve defined permissions
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
/permissions/effective:
|
||||
get:
|
||||
tags:
|
||||
- Permissions
|
||||
summary: Effective rules for current user
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: query
|
||||
name: resource
|
||||
description: Show only rules for a specific resource
|
||||
required: false
|
||||
schema: *ref_2
|
||||
'/permissions/{roleID}/rules':
|
||||
get:
|
||||
tags:
|
||||
- Permissions
|
||||
summary: Retrieve role permissions
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: roleID
|
||||
description: Role ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
delete:
|
||||
tags:
|
||||
- Permissions
|
||||
summary: Remove all defined role permissions
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: roleID
|
||||
description: Role ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
patch:
|
||||
tags:
|
||||
- Permissions
|
||||
summary: Update permission settings
|
||||
responses:
|
||||
'200':
|
||||
description: OK
|
||||
parameters:
|
||||
- in: path
|
||||
name: roleID
|
||||
description: Role ID
|
||||
required: true
|
||||
schema: *ref_5
|
||||
requestBody:
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties: &ref_16
|
||||
rules:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
roleID:
|
||||
type: string
|
||||
format: uuid
|
||||
resource:
|
||||
type: string
|
||||
operation:
|
||||
type: string
|
||||
access:
|
||||
type: string
|
||||
description: List of permission rules to set
|
||||
required:
|
||||
- rules
|
||||
application/x-www-form-urlencoded:
|
||||
schema:
|
||||
type: object
|
||||
properties: *ref_16
|
||||
@@ -1,774 +0,0 @@
|
||||
# User activity
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `POST` | `/activity/` | Sends user's activity to all subscribers; globally or per channel/message. |
|
||||
|
||||
## Sends user's activity to all subscribers; globally or per channel/message.
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/activity/` | HTTP/S | POST | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | POST | Channel ID, if set, activity will be send only to subscribed users | N/A | NO |
|
||||
| messageID | uint64 | POST | Message ID, if set, channelID must be set as well | N/A | NO |
|
||||
| kind | string | POST | Arbitrary string | N/A | YES |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Attachments
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/attachment/{attachmentID}/original/{name}` | Serves attached file |
|
||||
| `GET` | `/attachment/{attachmentID}/preview.{ext}` | Serves preview of an attached file |
|
||||
|
||||
## Serves attached file
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/attachment/{attachmentID}/original/{name}` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| download | bool | GET | Force file download | N/A | NO |
|
||||
| sign | string | GET | Signature | N/A | YES |
|
||||
| userID | uint64 | GET | User ID | N/A | YES |
|
||||
| name | string | PATH | File name | N/A | YES |
|
||||
| attachmentID | uint64 | PATH | Attachment ID | N/A | YES |
|
||||
|
||||
## Serves preview of an attached file
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/attachment/{attachmentID}/preview.{ext}` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| ext | string | PATH | Preview extension/format | N/A | YES |
|
||||
| attachmentID | uint64 | PATH | Attachment ID | N/A | YES |
|
||||
| sign | string | GET | Signature | N/A | YES |
|
||||
| userID | uint64 | GET | User ID | N/A | YES |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Channels
|
||||
|
||||
A channel is a representation of a sequence of messages. It has meta data like channel subject. Channels may be public, private or group.
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/channels/` | List channels |
|
||||
| `POST` | `/channels/` | Create new channel |
|
||||
| `PUT` | `/channels/{channelID}` | Update channel details |
|
||||
| `PUT` | `/channels/{channelID}/state` | Update channel state |
|
||||
| `PUT` | `/channels/{channelID}/flag` | Update channel membership flag |
|
||||
| `DELETE` | `/channels/{channelID}/flag` | Remove channel membership flag |
|
||||
| `GET` | `/channels/{channelID}` | Read channel details |
|
||||
| `GET` | `/channels/{channelID}/members` | List channel members |
|
||||
| `PUT` | `/channels/{channelID}/members/{userID}` | Join channel |
|
||||
| `DELETE` | `/channels/{channelID}/members/{userID}` | Remove member from channel |
|
||||
| `POST` | `/channels/{channelID}/invite` | Join channel |
|
||||
| `POST` | `/channels/{channelID}/attach` | Attach file to channel |
|
||||
|
||||
## List channels
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| query | string | GET | Search query | N/A | NO |
|
||||
|
||||
## Create new channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| name | string | POST | Name of Channel | N/A | NO |
|
||||
| topic | string | POST | Subject of Channel | N/A | NO |
|
||||
| type | string | POST | Channel type | N/A | NO |
|
||||
| membershipPolicy | types.ChannelMembershipPolicy | POST | Membership policy (eg: featured, forced)? | N/A | NO |
|
||||
| members | []string | POST | Initial members of the channel | N/A | NO |
|
||||
|
||||
## Update channel details
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}` | HTTP/S | PUT | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| name | string | POST | Name of Channel | N/A | NO |
|
||||
| topic | string | POST | Subject of Channel | N/A | NO |
|
||||
| membershipPolicy | types.ChannelMembershipPolicy | POST | Membership policy (eg: featured, forced)? | N/A | NO |
|
||||
| type | string | POST | Channel type | N/A | NO |
|
||||
| organisationID | uint64 | POST | Move channel to different organisation | N/A | NO |
|
||||
|
||||
## Update channel state
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/state` | HTTP/S | PUT | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| state | string | POST | Valid values: delete, undelete, archive, unarchive | N/A | YES |
|
||||
|
||||
## Update channel membership flag
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/flag` | HTTP/S | PUT | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| flag | string | POST | Valid values: pinned, hidden, ignored | N/A | YES |
|
||||
|
||||
## Remove channel membership flag
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/flag` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Read channel details
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## List channel members
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/members` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Join channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/members/{userID}` | HTTP/S | PUT | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| userID | uint64 | PATH | Member ID | N/A | NO |
|
||||
|
||||
## Remove member from channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/members/{userID}` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| userID | uint64 | PATH | Member ID | N/A | NO |
|
||||
|
||||
## Join channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/invite` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| userID | []string | POST | User ID | N/A | NO |
|
||||
|
||||
## Attach file to channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/attach` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| replyTo | uint64 | POST | Upload as a reply | N/A | NO |
|
||||
| upload | *multipart.FileHeader | POST | File to upload | N/A | YES |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Commands
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/commands/` | List of available commands |
|
||||
|
||||
## List of available commands
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/commands/` | HTTP/S | GET | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Messages
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `POST` | `/channels/{channelID}/messages/` | Post new message to the channel |
|
||||
| `POST` | `/channels/{channelID}/messages/command/{command}/exec` | Execute command |
|
||||
| `GET` | `/channels/{channelID}/messages/mark-as-read` | Manages read/unread messages in a channel or a thread |
|
||||
| `PUT` | `/channels/{channelID}/messages/{messageID}` | Edit existing message |
|
||||
| `DELETE` | `/channels/{channelID}/messages/{messageID}` | Delete existing message |
|
||||
| `POST` | `/channels/{channelID}/messages/{messageID}/replies` | Reply to a message |
|
||||
| `POST` | `/channels/{channelID}/messages/{messageID}/pin` | Pin message to channel (public bookmark) |
|
||||
| `DELETE` | `/channels/{channelID}/messages/{messageID}/pin` | Pin message to channel (public bookmark) |
|
||||
| `POST` | `/channels/{channelID}/messages/{messageID}/bookmark` | Bookmark a message (private bookmark) |
|
||||
| `DELETE` | `/channels/{channelID}/messages/{messageID}/bookmark` | Remove boomark from message (private bookmark) |
|
||||
| `POST` | `/channels/{channelID}/messages/{messageID}/reaction/{reaction}` | React to a message |
|
||||
| `DELETE` | `/channels/{channelID}/messages/{messageID}/reaction/{reaction}` | Delete reaction from a message |
|
||||
|
||||
## Post new message to the channel
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| message | string | POST | Message contents (markdown) | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Execute command
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/command/{command}/exec` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| command | string | PATH | Command to be executed | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| input | string | POST | Arbitrary command input | N/A | NO |
|
||||
| params | []string | POST | Command parameters | N/A | NO |
|
||||
|
||||
## Manages read/unread messages in a channel or a thread
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/mark-as-read` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| threadID | uint64 | GET | ID of thread (messageID) | N/A | NO |
|
||||
| lastReadMessageID | uint64 | GET | ID of the last read message | N/A | NO |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Edit existing message
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}` | HTTP/S | PUT | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| message | string | POST | Message contents (markdown) | N/A | YES |
|
||||
|
||||
## Delete existing message
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Reply to a message
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/replies` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
| message | string | POST | Message contents (markdown) | N/A | YES |
|
||||
|
||||
## Pin message to channel (public bookmark)
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/pin` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Pin message to channel (public bookmark)
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/pin` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Bookmark a message (private bookmark)
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/bookmark` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Remove boomark from message (private bookmark)
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/bookmark` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## React to a message
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/reaction/{reaction}` | HTTP/S | POST | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| reaction | string | PATH | Reaction | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
## Delete reaction from a message
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/channels/{channelID}/messages/{messageID}/reaction/{reaction}` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| messageID | uint64 | PATH | Message ID | N/A | YES |
|
||||
| reaction | string | PATH | Reaction | N/A | YES |
|
||||
| channelID | uint64 | PATH | Channel ID | N/A | YES |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Permissions
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/permissions/` | Retrieve defined permissions |
|
||||
| `GET` | `/permissions/effective` | Effective rules for current user |
|
||||
| `GET` | `/permissions/{roleID}/rules` | Retrieve role permissions |
|
||||
| `DELETE` | `/permissions/{roleID}/rules` | Remove all defined role permissions |
|
||||
| `PATCH` | `/permissions/{roleID}/rules` | Update permission settings |
|
||||
|
||||
## Retrieve defined permissions
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/permissions/` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
|
||||
## Effective rules for current user
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/permissions/effective` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| resource | string | GET | Show only rules for a specific resource | N/A | NO |
|
||||
|
||||
## Retrieve role permissions
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/permissions/{roleID}/rules` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| roleID | uint64 | PATH | Role ID | N/A | YES |
|
||||
|
||||
## Remove all defined role permissions
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/permissions/{roleID}/rules` | HTTP/S | DELETE | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| roleID | uint64 | PATH | Role ID | N/A | YES |
|
||||
|
||||
## Update permission settings
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/permissions/{roleID}/rules` | HTTP/S | PATCH | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| roleID | uint64 | PATH | Role ID | N/A | YES |
|
||||
| rules | permissions.RuleSet | POST | List of permission rules to set | N/A | YES |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Search entry point
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/search/messages` | Search for messages |
|
||||
| `GET` | `/search/threads` | Search for threads |
|
||||
|
||||
## Search for messages
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/search/messages` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | []string | GET | Filter by channels | N/A | NO |
|
||||
| afterMessageID | uint64 | GET | ID of the first message in the list (exclusive) | N/A | NO |
|
||||
| beforeMessageID | uint64 | GET | ID of the last message in the list (exclusive) | N/A | NO |
|
||||
| fromMessageID | uint64 | GET | ID of the first message in the list (inclusive) | N/A | NO |
|
||||
| toMessageID | uint64 | GET | ID of the last message the list (inclusive) | N/A | NO |
|
||||
| threadID | []string | GET | Filter by thread message ID | N/A | NO |
|
||||
| userID | []string | GET | Filter by one or more user | N/A | NO |
|
||||
| type | []string | GET | Filter by message type (text, inlineImage, attachment, ...) | N/A | NO |
|
||||
| pinnedOnly | bool | GET | Return only pinned messages | N/A | NO |
|
||||
| bookmarkedOnly | bool | GET | Only bookmarked messages | N/A | NO |
|
||||
| limit | uint | GET | Max number of messages | N/A | NO |
|
||||
| query | string | GET | Search query | N/A | NO |
|
||||
|
||||
## Search for threads
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/search/threads` | HTTP/S | GET | Client ID, Session ID |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| channelID | []string | GET | Filter by channels | N/A | NO |
|
||||
| limit | uint | GET | Max number of messages | N/A | NO |
|
||||
| query | string | GET | Search query | N/A | NO |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Settings
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/settings/` | List settings |
|
||||
| `PATCH` | `/settings/` | Update settings |
|
||||
| `GET` | `/settings/{key}` | Get a value for a key |
|
||||
| `GET` | `/settings/current` | Current compose settings |
|
||||
|
||||
## List settings
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/settings/` | HTTP/S | GET | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| prefix | string | GET | Key prefix | N/A | NO |
|
||||
|
||||
## Update settings
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/settings/` | HTTP/S | PATCH | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| values | settings.ValueSet | POST | Array of new settings: `[{ name: ..., value: ... }]`. Omit value to remove setting | N/A | YES |
|
||||
|
||||
## Get a value for a key
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/settings/{key}` | HTTP/S | GET | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| ownerID | uint64 | GET | Owner ID | N/A | NO |
|
||||
| key | string | PATH | Setting key | N/A | YES |
|
||||
|
||||
## Current compose settings
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/settings/current` | HTTP/S | GET | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
# Status
|
||||
|
||||
| Method | Endpoint | Purpose |
|
||||
| ------ | -------- | ------- |
|
||||
| `GET` | `/status/` | See all current statuses |
|
||||
| `POST` | `/status/` | Set user's status |
|
||||
| `DELETE` | `/status/` | Clear status |
|
||||
|
||||
## See all current statuses
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/status/` | HTTP/S | GET | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
|
||||
## Set user's status
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/status/` | HTTP/S | POST | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
| icon | string | POST | Status icon | N/A | NO |
|
||||
| message | string | POST | Status message | N/A | NO |
|
||||
| expires | string | POST | Clear status when it expires (eg: when-active, afternoon, tomorrow 1h, 30m, 1 PM, 2019-05-20) | N/A | NO |
|
||||
|
||||
## Clear status
|
||||
|
||||
#### Method
|
||||
|
||||
| URI | Protocol | Method | Authentication |
|
||||
| --- | -------- | ------ | -------------- |
|
||||
| `/status/` | HTTP/S | DELETE | |
|
||||
|
||||
#### Request parameters
|
||||
|
||||
| Parameter | Type | Method | Description | Default | Required? |
|
||||
| --------- | ---- | ------ | ----------- | ------- | --------- |
|
||||
|
||||
---
|
||||
File diff suppressed because one or more lines are too long
+1781
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,18 @@
|
||||
package api
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/cortezaproject/corteza-server/docs"
|
||||
"github.com/goware/statik/fs"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
func serveDocs(w http.ResponseWriter, r *http.Request) {
|
||||
root, err := fs.New(docs.Asset)
|
||||
if err != nil {
|
||||
http.Error(w, fmt.Sprintf("could not read embeded filesystem: %v", err.Error()), http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
http.StripPrefix("/docs", http.FileServer(root)).ServeHTTP(w, r)
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
package server
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/cortezaproject/corteza-server/docs"
|
||||
"github.com/goware/statik/fs"
|
||||
"net/http"
|
||||
)
|
||||
|
||||
func serveDocs(w http.ResponseWriter, r *http.Request) {
|
||||
root, err := fs.New(docs.Asset)
|
||||
if err != nil {
|
||||
http.Error(w, fmt.Sprintf("could not read embeded filesystem: %v", err.Error()), http.StatusInternalServerError)
|
||||
return
|
||||
}
|
||||
|
||||
http.StripPrefix("/docs", http.FileServer(root)).ServeHTTP(w, r)
|
||||
}
|
||||
@@ -143,4 +143,7 @@ func (s server) bindMiscRoutes(router chi.Router) {
|
||||
if s.httpOpt.EnableHealthcheckRoute {
|
||||
router.Get("/healthcheck", healthcheck.HttpHandler())
|
||||
}
|
||||
|
||||
//router.Group(serveDocs2)
|
||||
router.HandleFunc("/docs*", serveDocs)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user